zsElectric-openapi

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脚本:

-- 创建开放平台应用信息表
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 中的数据库连接信息:

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安全配置:

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

4. 编译运行

# 编译项目
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. 获取访问令牌

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

响应:

{
  "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()

示例:

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} - 查询订单详情

部署说明

打包部署

# 打包
mvn clean package

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

生产环境配置

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

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

启动服务

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

# 查看日志
tail -f app.log

Docker部署

创建 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"]

构建并运行:

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