# zsElectric-OpenApi 开放平台服务

## 项目简介

zsElectric-OpenApi 是一个独立的开放平台API服务,提供第三方应用调用的接口服务。该服务可以独立部署到服务器上,对外提供RESTful API接口。

## 技术栈

- **Java**: 17
- **Spring Boot**: 3.5.6
- **MyBatis Plus**: 3.5.5
- **Druid**: 1.2.24
- **Hutool**: 5.8.34
- **Knife4j**: 4.5.0 (API文档)
- **MySQL**: 8.0+
- **Lombok**: 工具类

## 项目结构

```
zsElectric-openapi/
├── src/
│   ├── main/
│   │   ├── java/com/zsElectric/openapi/
│   │   │   ├── config/          # 配置类
│   │   │   ├── controller/      # 控制器
│   │   │   ├── service/         # 服务层
│   │   │   ├── entity/          # 实体类
│   │   │   ├── mapper/          # MyBatis Mapper
│   │   │   ├── common/          # 公共类
│   │   │   ├── dto/             # 数据传输对象
│   │   │   ├── vo/              # 视图对象
│   │   │   ├── security/        # 安全相关
│   │   │   └── ZsElectricOpenApiApplication.java
│   │   └── resources/
│   │       ├── application.yml          # 主配置文件
│   │       ├── application-dev.yml      # 开发环境配置
│   │       ├── application-prod.yml     # 生产环境配置
│   │       └── mapper/                  # MyBatis映射文件
│   └── test/
├── pom.xml
└── README.md
```

## 快速开始

### 1. 环境要求

- JDK 17+
- Maven 3.6+
- MySQL 8.0+

### 2. 数据库初始化

创建数据库并执行以下SQL脚本:

```sql
-- 创建开放平台应用信息表
CREATE TABLE `openapi_app_info` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `app_id` varchar(64) NOT NULL COMMENT '应用ID',
  `app_name` varchar(128) NOT NULL COMMENT '应用名称',
  `app_secret` varchar(128) NOT NULL COMMENT '应用密钥',
  `contact_name` varchar(64) DEFAULT NULL COMMENT '联系人',
  `contact_phone` varchar(20) DEFAULT NULL COMMENT '联系电话',
  `contact_email` varchar(128) DEFAULT NULL COMMENT '联系邮箱',
  `callback_url` varchar(512) DEFAULT NULL COMMENT '回调地址',
  `ip_whitelist` varchar(1024) DEFAULT NULL COMMENT 'IP白名单',
  `status` tinyint DEFAULT '1' COMMENT '状态:0-禁用,1-启用',
  `daily_limit` int DEFAULT '10000' COMMENT '每日调用限额',
  `permissions` json DEFAULT NULL COMMENT '权限列表',
  `remark` varchar(512) DEFAULT NULL COMMENT '备注信息',
  `create_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `update_time` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_app_id` (`app_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='开放平台应用信息表';

-- 创建API调用日志表
CREATE TABLE `openapi_api_log` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `app_id` varchar(64) NOT NULL COMMENT '应用ID',
  `api_path` varchar(512) NOT NULL COMMENT '接口路径',
  `request_method` varchar(10) NOT NULL COMMENT '请求方法',
  `request_params` text COMMENT '请求参数',
  `request_ip` varchar(64) DEFAULT NULL COMMENT '请求IP',
  `response_code` int DEFAULT NULL COMMENT '响应状态码',
  `response_message` varchar(512) DEFAULT NULL COMMENT '响应消息',
  `response_time` bigint DEFAULT NULL COMMENT '响应时间(ms)',
  `success` tinyint DEFAULT NULL COMMENT '是否成功:0-失败,1-成功',
  `error_message` text COMMENT '错误信息',
  `request_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '请求时间',
  `response_time_field` datetime DEFAULT NULL COMMENT '响应时间',
  PRIMARY KEY (`id`),
  KEY `idx_app_id` (`app_id`),
  KEY `idx_request_time` (`request_time`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='API调用日志表';

-- 插入测试应用
INSERT INTO `openapi_app_info` (`app_id`, `app_name`, `app_secret`, `contact_name`, `contact_phone`, `status`)
VALUES ('TEST_APP_001', '测试应用', 'test_secret_123456', '测试人员', '13800138000', 1);
```

### 3. 配置修改

修改 `application-dev.yml` 中的数据库连接信息:

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/zs_electric?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=true&serverTimezone=GMT%2B8
    username: root
    password: your_password
```

修改 `application.yml` 中的API安全配置:

```yaml
api:
  security:
    secret-key: your-secret-key-please-change-in-production  # 生产环境请修改
    timestamp-expire-minutes: 5
    token-expire-hours: 24
    rate-limit: 100
```

### 4. 编译运行

```bash
# 编译项目
mvn clean package

# 运行项目
java -jar target/zsElectric-openapi.jar

# 或者指定环境
java -jar target/zsElectric-openapi.jar --spring.profiles.active=prod
```

### 5. 访问文档

服务启动后,访问以下地址查看API文档:

- **Knife4j文档**: http://localhost:8081/openapi/doc.html
- **Swagger UI**: http://localhost:8081/openapi/swagger-ui.html

## API调用流程

### 1. 获取访问令牌

```http
POST /openapi/api/v1/token/get
Content-Type: application/json
X-App-Id: TEST_APP_001
X-App-Secret: test_secret_123456
```

响应:

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "accessToken": "A1B2C3D4E5F6G7H8I9J0",
    "tokenType": "Bearer",
    "expireTime": 1704067200000
  },
  "timestamp": 1703980800000
}
```

### 2. API签名认证

所有需要认证的API请求都需要包含以下请求头:

- `X-App-Id`: 应用ID
- `X-Timestamp`: 时间戳(毫秒)
- `X-Nonce`: 随机字符串
- `X-Signature`: 签名(MD5)

签名生成算法:

```
signString = appId + timestamp + nonce + requestParams + secretKey
signature = MD5(signString).toUpperCase()
```

示例:

```http
GET /openapi/api/v1/charging/stations?status=AVAILABLE
X-App-Id: TEST_APP_001
X-Timestamp: 1703980800000
X-Nonce: random123456
X-Signature: AABBCCDD11223344556677889900
```

### 3. 调用API

使用获取到的令牌和签名调用具体的API接口。

## API接口列表

### 健康检查
- `GET /api/v1/health/check` - 健康检查

### 令牌管理
- `POST /api/v1/token/get` - 获取访问令牌

### 充电桩管理
- `GET /api/v1/charging/stations` - 获取充电桩列表
- `GET /api/v1/charging/stations/{stationId}` - 获取充电桩详情
- `GET /api/v1/charging/stations/{stationId}/status` - 获取充电桩实时状态

### 订单管理
- `GET /api/v1/order/list` - 查询订单列表
- `GET /api/v1/order/{orderId}` - 查询订单详情

## 部署说明

### 打包部署

```bash
# 打包
mvn clean package

# 生成的jar包位于: target/zsElectric-openapi.jar
```

### 生产环境配置

修改 `application-prod.yml` 中的配置:

- 数据库连接信息
- 日志路径
- API密钥
- 其他生产环境特定配置

### 启动服务

```bash
# 后台启动
nohup java -jar zsElectric-openapi.jar --spring.profiles.active=prod > app.log 2>&1 &

# 查看日志
tail -f app.log
```

### Docker部署

创建 `Dockerfile`:

```dockerfile
FROM openjdk:17-jdk-alpine
VOLUME /tmp
ADD target/zsElectric-openapi.jar app.jar
ENTRYPOINT ["java","-Djava.security.egd=file:/dev/./urandom","-jar","/app.jar"]
```

构建并运行:

```bash
docker build -t zselectric-openapi:1.0.0 .
docker run -d -p 8081:8081 --name openapi zselectric-openapi:1.0.0
```

## 安全建议

1. **生产环境必须修改**:
   - API签名密钥 (`api.security.secret-key`)
   - 数据库密码
   - 应用密钥 (`app_secret`)

2. **使用HTTPS**: 生产环境必须使用HTTPS协议

3. **IP白名单**: 为每个应用配置IP白名单

4. **限流控制**: 根据业务需求调整API调用频率限制

5. **日志监控**: 定期查看API调用日志,及时发现异常

6. **权限控制**: 为不同应用分配不同的权限

## 常见问题

### Q: 签名验证失败?
A: 请检查:
- 签名算法是否正确
- 时间戳是否在有效期内(默认5分钟)
- 请求参数是否包含在签名中
- 密钥是否正确

### Q: 时间戳过期?
A: 请确保客户端时间与服务器时间同步,误差不超过配置的过期时间(默认5分钟)

### Q: 如何限制应用调用频率?
A: 在 `openapi_app_info` 表中设置 `daily_limit` 字段,或在 `application.yml` 中配置 `api.security.rate-limit`

## 联系方式

- 项目作者: Ray.Hao
- 技术支持: support@zselectric.com