ChronicDisease_SpringBoot/docs/DevRule/03-API设计规范.md

API设计规范

概述

本规范基于项目现有代码实现，定义了API接口的设计原则和标准。所有API必须遵循RESTful设计理念，确保接口的一致性、可维护性和易用性。

基本原则

1. RESTful设计：使用RESTful风格的URL路径，资源导向的设计理念。
2. 统一响应格式：所有API响应必须使用统一的R<T>格式。
3. 状态码规范：使用HTTP状态码和业务状态码相结合的方式。
4. 认证授权：采用Token-based认证机制。
5. 错误处理：统一的异常处理机制。

URL路径设计

1. 路径结构：

   • 使用小写字母和连字符（-）分隔单词
   • 路径格式：/{resource}/{action} 或 /{resource}/{id}/{action}
   • 示例：/geo/nearest, /get_openid, /user_info

2. 控制器映射：

   • 使用@RequestMapping("/{module}")定义模块路径
   • 子路径使用@GetMapping, @PostMapping等注解

HTTP方法

• GET：查询操作，用于获取资源
• POST：创建或执行操作，用于提交数据或执行动作
• PUT：更新操作（项目中暂未使用）
• DELETE：删除操作（项目中暂未使用）

请求格式

1. Content-Type：

   • JSON请求：application/json
   • 使用@RequestBody注解接收JSON数据

2. 参数传递：

   • 查询参数：使用@RequestParam
   • 请求体：使用@RequestBody
   • 路径参数：使用@PathVariable（项目中暂未使用）

响应格式

1. 统一响应类：R<T>

   {
      "code": Integer,    // 状态码
      "message": String,  // 响应消息
      "data": T          // 响应数据，可为空
   }
   

2. 成功响应：

   • 状态码：200
   • 使用R.success(code, message, data)构造

3. 失败响应：

   • 状态码：400（参数错误）、500（服务器错误）
   • 使用R.fail(code, message)构造

状态码规范

1. 成功状态码：

   • 200：操作成功
   • 具体业务成功码定义在SuccessResultCode枚举中

2. 失败状态码：

   • 400：参数校验异常、请求参数错误
   • 500：服务器内部错误
   • 具体业务失败码定义在ErrorCode枚举中

3. 异常状态码：

   • 定义在ErrorCode枚举中
   • 包括各种业务相关的错误码，如参数错误、资源不存在等

认证与授权

1. 认证方式：

   • 优先使用标准 Authorization header：Authorization: Bearer <token>（AuthInterceptor 优先解析该方式）
   • 向后兼容支持：X-Token 或 token header
   • 注意：AuthInterceptor 当前实现通过请求头解析 token（Authorization、X-Token、token），并不直接读取请求 body。若需要从 body 中提取 token，请在 Controller 层明确定义并处理。

2. 拦截器配置：

   • AuthInterceptor 负责 Token 校验并在校验通过后把 currentUserId/currentUserRole 放入 request attribute
   • 排除路径：/、/get_openid、/v3/api-docs/**, /swagger-ui/**, /doc.html, /webjars/**, /favicon.ico 等（参见 WebMvcConfig 的 excludePathPatterns）

3. Token管理：

   • 使用TokenService生成和校验Token
   • 校验通过后将userId放入request属性

错误处理

1. 全局异常处理器：CustomExceptionHandler

   • 处理BindException：参数绑定异常
   • 处理ConstraintViolationException：约束违反异常
   • 处理CustomException：自定义业务异常
   • 处理Exception：未知异常

2. 异常响应：

   • 统一返回R.fail(code, message)格式
   • 记录错误日志

分页处理

1. 分页类：Page<T>

   {
      "pageNum": int,     // 当前页码
      "pageSize": int,    // 每页大小
      "total": long,      // 总记录数
      "list": List<T>     // 数据列表
   }
   

2. 分页插件：使用pagehelper实现分页

   • 配置在application.yml中
   • 数据库方言：MySQL

跨域配置

1. CORS配置：CorsConfig
   • 实际实现：CorsConfig.addCorsMappings 当前对所有路径 /** 开放跨域（本地开发场景），并允许源 http://localhost:3000。
   • 允许方法：GET, POST, PUT, DELETE, OPTIONS
   • 允许头：*（允许所有请求头）并暴露头 X-Custom-Header, X-Token, Authorization 给前端
   • 允许凭证：true

API文档

1. 文档工具：使用 Knife4j / springdoc-openapi（基于 OpenAPI 3）

   • Knife4jConfig 中配置了 OpenAPI 的基本信息（title、description、version）并通过 GroupedOpenApi 扫描包 work.baiyun.chronicdiseaseapp。
   • 默认本地服务器地址配置为 http://localhost:8080，版本号在 OpenAPI info 中设置为 v1。
   • 访问路径：/doc.html（Knife4j UI）或 springdoc 的 /v3/api-docs。

2. 字段描述：

   • 使用@Schema注解描述请求/响应字段

   • 示例：

     @Schema(description = "更新用户信息请求")
     public class UpdateUserInfoRequest {
     @Schema(description = "头像（可选）")
     private String avatar;
     }
     

安全考虑

1. 输入验证：使用Bean Validation注解
2. SQL注入防护：使用MyBatis-Plus预编译
3. XSS防护：前端负责，API层不额外处理
4. 敏感信息：不在日志中记录Token等敏感信息

版本控制

• 当前API版本：v0
• 版本信息在Swagger配置中定义
• 未来版本升级时，可通过URL路径前缀区分（如/v1/、/v2/）

性能优化

1. 连接池：使用HikariCP数据库连接池
2. 缓存：根据业务需要添加缓存机制（项目中暂未实现）
3. 异步处理：对于耗时操作可考虑异步处理（项目中暂未使用）

测试规范

• API接口应编写单元测试和集成测试
• 测试应覆盖正常流程和异常情况
• 使用Mock框架模拟依赖服务

关于长整型 ID 的传输策略（补充）

说明：项目使用雪花算法（Snowflake）生成的主键/业务 ID 为 64 位长整型（BIGINT / Long），在前端 JavaScript 中直接使用 Number 类型可能会发生精度丢失。为避免前端显示与处理错误，API 层对外响应时应把此类 ID 以字符串形式返回。

要点：

• 在对外响应的 DTO/VO 中，将 id 字段定义为 String（响应侧）。请求参数可继续使用 Long/BigInt（后端解析/校验）。
• 在时序/批量返回场景（List/分页）中，同样应保证 id 字段为字符串类型。
• 在 OpenAPI/Swagger 注释中显式标注字段类型为 string，并在说明中写明其实际在数据库/业务中的原始类型为 Long/BIGINT。

示例（响应 VO 与转换）：

public class PhysicalDataResponse {
   @Schema(description = "记录ID，数据库类型为BIGINT，JSON返回为字符串")
   private String id; // 对外返回 String
   // ... 其他字段
}

// 服务层转换示例
PhysicalDataResponse r = new PhysicalDataResponse();
BeanUtils.copyProperties(record, r);
if (record.getId() != null) {
   r.setId(record.getId().toString());
}

兼容性与说明：

• 该约定属于接口契约变更（响应字段类型从 number -> string），在发布到生产前请在 API 文档、变更日志与前端团队进行告知并做好契约验证（可用契约测试）。
• 若需要向下兼容旧客户端，可考虑在文档中说明旧客户端如何兼容（例如前端接收到字符串后显式转换为 BigInt 或按字符串处理）。