REST API

目录

  1. 简介
  2. 认证机制
  3. 通用响应格式
  4. 分页查询参数
  5. 全局异常处理
  6. 错误码列表
  7. 用户认证API
  8. 设备管理API
  9. 协议交互API
  10. 远程过程调用API
  11. curl命令示例

简介

本文档为MultiProtocol系统提供全面的REST API文档，涵盖用户认证、设备管理、协议交互和远程过程调用等核心功能。所有API端点均采用统一的响应格式和错误处理机制，确保接口的一致性和易用性。

  • [StationController.java](file://mp-app/src/main/java/com/witos/mp/app/adapter/controller/StationController.java)
  • [PileController.java](file://mp-app/src/main/java/com/witos/mp/app/adapter/controller/PileController.java)
  • [GunController.java](file://mp-app/src/main/java/com/witos/mp/app/adapter/controller/GunController.java)
  • [ProtocolController.java](file://mp-app/src/main/java/com/witos/mp/app/adapter/controller/ProtocolController.java)
  • [RpcController.java](file://mp-app/src/main/java/com/witos/mp/app/adapter/controller/RpcController.java)

认证机制

系统采用JWT（JSON Web Token）进行身份认证和授权。客户端在成功登录后会获得一个JWT令牌，后续请求需要在请求头中携带该令牌。

认证方式

支持以下两种方式传递JWT令牌：

  1. Authorization请求头（推荐）

    Authorization: Bearer <JWT_TOKEN>

  2. 自定义请求头

    X-Authorization: <JWT_TOKEN>

认证流程

  1. 用户通过/api/auth/login端点进行登录，提供用户名和密码
  2. 服务器验证凭据，成功后返回包含JWT令牌的响应
  3. 客户端在后续所有请求的请求头中包含JWT令牌
  4. 服务器验证令牌的有效性，决定是否授予访问权限

令牌过期后，客户端需要使用刷新令牌获取新的访问令牌。

  • [SecurityConfiguration.java](file://mp-app/src/main/java/com/witos/mp/app/service/security/SecurityConfiguration.java)
  • [LoginResponse.java](file://mp-app/src/main/java/com/witos/mp/app/adapter/response/LoginResponse.java)

通用响应格式

所有API响应均采用统一的ApiResponse格式，确保客户端能够一致地处理成功和错误响应。

响应结构

{
  "success": true,
  "errorCode": "SUCCESS",
  "message": "操作成功",
  "data": {},
  "timestamp": 1700000000000
}

字段说明

  • success: 布尔值，表示请求是否成功
  • errorCode: 错误码，成功时为"SUCCESS"，失败时为具体的错误码
  • message: 响应消息，描述操作结果
  • data: 响应数据，包含实际的业务数据
  • timestamp: 时间戳，记录响应生成的时间

成功响应示例

{
  "success": true,
  "errorCode": "SUCCESS",
  "message": "查询成功",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "stationName": "测试充电站",
    "stationCode": "ST001"
  },
  "timestamp": 1700000000000
}

错误响应示例

{
  "success": false,
  "errorCode": "UNAUTHORIZED",
  "message": "用户未认证",
  "timestamp": 1700000000000
}
  • [ApiResponse.java](file://mp-app/src/main/java/com/witos/mp/app/adapter/response/ApiResponse.java)

分页查询参数

大多数查询接口支持分页功能，通过PageRequest类定义分页参数。

分页参数

参数名类型必填默认值说明
pageInteger否1页码，从1开始
sizeInteger否10每页大小
sortFieldString否-排序字段
sortOrderString否desc排序方向：asc(升序)或desc(降序)
searchString否-搜索关键词

示例

获取第2页的充电站列表，每页20条记录，按创建时间降序排列：

GET /api/stations?page=2&size=20&sortField=createTime&sortOrder=desc
  • [PageRequest.java](file://mp-app/src/main/java/com/witos/mp/app/adapter/request/PageRequest.java)

全局异常处理

系统通过BaseController类提供统一的异常处理机制，确保所有异常都能被妥善处理并返回标准化的错误响应。

异常处理流程

  1. 捕获控制器中的各种异常
  2. 将异常转换为MpException
  3. 通过MpErrorResponseHandler生成标准化的错误响应
  4. 返回给客户端

支持的异常类型

  • Exception: 通用异常

  • MpException: Mp自定义异常

  • MethodArgumentNotValidException: 参数校验异常

  • [BaseController.java](file://mp-app/src/main/java/com/witos/mp/app/adapter/controller/BaseController.java)

  • [MpErrorResponseHandler.java](file://mp-app/src/main/java/com/witos/mp/app/exception/MpErrorResponseHandler.java)

错误码列表

系统定义了统一的错误码体系，便于客户端识别和处理不同类型的错误。

通用错误码

错误码说明
SUCCESS操作成功
SYSTEM_ERROR系统异常，请稍后重试
BUSINESS_ERROR业务处理失败
VALIDATION_ERROR参数校验失败
BINDING_ERROR数据绑定异常
ILLEGAL_ARGUMENT参数错误
ILLEGAL_STATE状态错误

认证授权相关

错误码说明
UNAUTHORIZED用户未认证
AUTH_FAILED用户名或密码错误
JWT_AUTH_FAILEDJWT Token认证失败
FORBIDDEN权限不足

资源相关

错误码说明
NOT_FOUND请求的资源不存在
CONFLICT资源冲突

业务特定错误码

错误码说明
PILE_CODE_EXISTS充电桩编码已存在
STATION_NAME_EXISTS充电站名称已存在
GUN_CODE_EXISTS充电枪编号已存在
PILE_NOT_FOUND充电桩不存在
STATION_NOT_FOUND充电站不存在
GUN_NOT_FOUND充电枪不存在
  • [ErrorCode.java](file://mp-app/src/main/java/com/witos/mp/app/adapter/response/ErrorCode.java)
  • [MpErrorCode.java](file://mp-app/src/main/java/com/witos/mp/app/exception/MpErrorCode.java)

用户认证API

提供用户登录和获取用户信息的接口。

登录

  • HTTP方法: POST
  • URL路径: /api/auth/login
  • 请求头: 无特殊要求
  • 请求体:
    {
  "username": "string",
  "password": "string"
}
  • 响应体:
    {
  "success": true,
  "errorCode": "SUCCESS",
  "message": "操作成功",
  "data": {
    "token": "string",
    "refreshToken": "string",
    "tokenType": "Bearer",
    "user": {
      "id": "string",
      "username": "string",
      "status": "ENABLE"
    }
  },
  "timestamp": 1700000000000
}

获取用户信息

  • HTTP方法: GET

  • URL路径: /api/user/info

  • 请求头: Authorization: Bearer <JWT>

  • 响应体:

    {
  "success": true,
  "errorCode": "SUCCESS",
  "message": "操作成功",
  "data": {
    "id": "string",
    "username": "string",
    "status": "ENABLE"
  },
  "timestamp": 1700000000000
}

  • [UserController.java](file://mp-app/src/main/java/com/witos/mp/app/adapter/controller/UserController.java)

  • [LoginResponse.java](file://mp-app/src/main/java/com/witos/mp/app/adapter/response/LoginResponse.java)

设备管理API

提供对充电站、充电桩和充电枪的增删改查操作。

充电站管理

查询充电站列表

  • HTTP方法: GET
  • URL路径: /api/stations
  • 请求头: Authorization: Bearer <JWT>
  • 查询参数: 继承自PageRequest
  • 响应体:
    {
  "success": true,
  "errorCode": "SUCCESS",
  "message": "查询成功",
  "data": {
    "content": [
      {
        "id": "uuid",
        "stationName": "string",
        "stationCode": "string",
        "longitude": 120.123,
        "latitude": 30.456,
        "province": "string",
        "city": "string",
        "county": "string",
        "address": "string"
      }
    ],
    "totalElements": 1,
    "totalPages": 1,
    "page": 1,
    "size": 10
  },
  "timestamp": 1700000000000
}

创建充电站

  • HTTP方法: POST

  • URL路径: /api/stations

  • 请求头: Authorization: Bearer <JWT>

  • 请求体: StationCreateRequest

    {
  "stationName": "string",
  "stationCode": "string",
  "longitude": 120.123,
  "latitude": 30.456,
  "province": "string",
  "city": "string",
  "county": "string",
  "address": "string"
}

  • 字段说明:

    • stationName: 充电站名称，必填，不能为空
    • stationCode: 充电站编码，必填，不能为空
    • longitude: 经度，浮点数
    • latitude: 纬度，浮点数
    • province: 省份
    • city: 城市
    • county: 区县
    • address: 详细地址

  • [StationController.java](file://mp-app/src/main/java/com/witos/mp/app/adapter/controller/StationController.java)

  • [StationCreateRequest.java](file://mp-app/src/main/java/com/witos/mp/app/adapter/request/StationCreateRequest.java)

更新充电站

  • HTTP方法: PUT
  • URL路径: /api/stations/{id}
  • 请求头: Authorization: Bearer <JWT>
  • 路径参数: id - 充电站ID (UUID)
  • 请求体: StationUpdateRequest
    {
  "stationName": "string",
  "longitude": 120.123,
  "latitude": 30.456,
  "province": "string",
  "city": "string",
  "county": "string",
  "address": "string"
}

删除充电站

  • HTTP方法: DELETE
  • URL路径: /api/stations/{id}
  • 请求头: Authorization: Bearer <JWT>
  • 路径参数: id - 充电站ID (UUID)

充电桩管理

创建充电桩

  • HTTP方法: POST

  • URL路径: /api/piles

  • 请求头: Authorization: Bearer <JWT>

  • 请求体: PileCreateRequest

    {
  "pileName": "string",
  "pileCode": "string",
  "protocol": "string",
  "stationId": "uuid",
  "brand": "string",
  "model": "string",
  "manufacturer": "string",
  "type": "DC"
}

  • 字段说明:

    • pileName: 充电桩名称，必填，不能为空
    • pileCode: 充电桩编码，必填，不能为空
    • protocol: 协议，必填，不能为空
    • stationId: 所属充电站ID，必填，不能为空
    • brand: 品牌
    • model: 型号
    • manufacturer: 制造商
    • type: 类型，默认为DC（直流）

  • [PileController.java](file://mp-app/src/main/java/com/witos/mp/app/adapter/controller/PileController.java)

  • [PileCreateRequest.java](file://mp-app/src/main/java/com/witos/mp/app/adapter/request/PileCreateRequest.java)

查询充电桩列表

  • HTTP方法: GET
  • URL路径: /api/piles
  • 请求头: Authorization: Bearer <JWT>
  • 查询参数: 继承自PageRequest
  • 响应体:
    {
  "success": true,
  "errorCode": "SUCCESS",
  "message": "查询成功",
  "data": {
    "content": [
      {
        "id": "uuid",
        "pileName": "string",
        "pileCode": "string",
        "protocol": "string",
        "stationId": "uuid",
        "brand": "string",
        "model": "string",
        "manufacturer": "string",
        "type": "DC",
        "status": "string"
      }
    ],
    "totalElements": 1,
    "totalPages": 1,
    "page": 1,
    "size": 10
  },
  "timestamp": 1700000000000
}

充电枪管理

创建充电枪

  • HTTP方法: POST

  • URL路径: /api/guns

  • 请求头: Authorization: Bearer <JWT>

  • 请求体: GunCreateRequest

    {
  "gunName": "string",
  "gunNo": "string",
  "gunCode": "string",
  "stationId": "uuid",
  "pileId": "uuid"
}

  • 字段说明:

    • gunName: 充电枪名称，必填，不能为空
    • gunNo: 充电枪编号，必填，不能为空
    • gunCode: 充电枪编码，必填，不能为空
    • stationId: 所属充电站ID，必填，不能为空
    • pileId: 所属充电桩ID，必填，不能为空

  • [GunController.java](file://mp-app/src/main/java/com/witos/mp/app/adapter/controller/GunController.java)

  • [GunCreateRequest.java](file://mp-app/src/main/java/com/witos/mp/app/adapter/request/GunCreateRequest.java)

协议交互API

提供协议相关的查询接口。

获取支持的协议列表

  • HTTP方法: GET

  • URL路径: /api/protocols/supported

  • 请求头: Authorization: Bearer <JWT>

  • 响应体:

    {
  "success": true,
  "errorCode": "SUCCESS",
  "message": "查询成功",
  "data": [
    {
      "value": "LVNENG_V340",
      "label": "绿能V3.4.0"
    },
    {
      "value": "YUNKUAICHONG_V150",
      "label": "云快充V1.5.0"
    }
  ],
  "timestamp": 1700000000000
}

  • [ProtocolController.java](file://mp-app/src/main/java/com/witos/mp/app/adapter/controller/ProtocolController.java)

远程过程调用API

提供通用化的充电桩下行指令接口。

单向RPC

  • HTTP方法: POST

  • URL路径: /api/rpc/oneway

  • 请求头: Authorization: Bearer <JWT>

  • 请求体: RpcRequest

    {
  "method": "string",
  "parameter": {},
  "timeoutMs": 10000
}

  • 字段说明:

    • method: RPC方法名，必填，不能为空
    • parameter: 方法参数，JSON格式，必填，不能为空
    • timeoutMs: 超时时间（毫秒），仅用于双向RPC

  • [RpcController.java](file://mp-app/src/main/java/com/witos/mp/app/adapter/controller/RpcController.java)

  • [RpcRequest.java](file://mp-app/src/main/java/com/witos/mp/app/adapter/request/RpcRequest.java)

支持的方法

方法名说明参数结构
startCharge启动充电StartChargeDTO
stopCharge停止充电StopChargeDTO
restartPile重启充电桩RestartPileDTO
setPricing设置计费策略SetPricingDTO
setQrcode设置二维码SetQrcodeRequest
otaRequestOTA升级OtaRequest
offlineCardBalanceUpdate离线卡余额更新OfflineCardBalanceUpdateRequest
offlineCardSync离线卡同步OfflineCardSyncRequest
offlineCardClear离线卡清除OfflineCardClearRequest
offlineCardQuery离线卡查询OfflineCardQueryRequest
timeSync时间同步TimeSyncDTO

启动充电示例

{
  "method": "startCharge",
  "parameter": {
    "pileCode": "P001",
    "gunNo": "G01",
    "limitYuan": 100.00,
    "orderNo": "ORDER_001",
    "logicalCardNo": "LOGICAL_001",
    "physicalCardNo": "PHYSICAL_001",
    "parallelNo": "PARALLEL_001"
  }
}
  • [StartChargeDTO.java](file://mp-app/src/main/java/com/witos/mp/app/adapter/dto/StartChargeDTO.java)

curl命令示例

以下是一些常用的curl命令示例，演示如何使用API。

登录

curl -X POST "http://localhost:8080/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "password"
  }'

查询电站列表

curl -X GET "http://localhost:8080/api/stations?page=1&size=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

下发启动充电指令

curl -X POST "http://localhost:8080/api/rpc/oneway" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "method": "startCharge",
    "parameter": {
      "pileCode": "P001",
      "gunNo": "G01",
      "limitYuan": 100.00,
      "orderNo": "ORDER_001"
    }
  }'
  • [UserController.java](file://mp-app/src/main/java/com/witos/mp/app/adapter/controller/UserController.java)
  • [StationController.java](file://mp-app/src/main/java/com/witos/mp/app/adapter/controller/StationController.java)
  • [RpcController.java](file://mp-app/src/main/java/com/witos/mp/app/adapter/controller/RpcController.java)
最近更新：:
Contributors: feng