docs: 创建 API 接口设计规范

2026-03-08 21:44:07 +08:00
parent ad56253552
commit 7c1c9e5fe5
1 changed files with 588 additions and 0 deletions
@@ -0,0 +1,588 @@
 # 健身房管理系统 API 接口设计规范
 > 文档编号：GYM-API-SPEC-001  
 > 版本：v1.0  
 > 创建日期：2026-03-08  
 > 最后更新日期：2026-03-08  
 > 作者：张翔  
 > 状态：正式发布
 ## 文档修订历史
 | 版本 | 日期 | 作者 | 修订内容 |
 | ---- | ---------- | ---- | -------- |
 | v1.0 | 2026-03-08 | 张翔 | 创建 API 接口设计规范 |
 ## 参考文档
 - RESTful API 最佳实践
 - OpenAPI 3.0 规范
 - Spring WebFlux 官方文档
 - RSocket 规范
 ---
 ## 一、API 设计原则
 ### 1.1 RESTful 风格
 **资源导向**：
 - 使用名词表示资源，不使用动词
 - 使用 HTTP 方法表示操作
 - 使用复数名词表示资源集合
 **示例**：
 ```
 ✅ GET /api/v1/members          # 获取会员列表
 ✅ POST /api/v1/members         # 创建会员
 ✅ GET /api/v1/members/{id}     # 获取单个会员
 ✅ PUT /api/v1/members/{id}     # 更新会员
 ✅ DELETE /api/v1/members/{id}  # 删除会员
 ❌ GET /api/v1/getMembers
 ❌ POST /api/v1/createMember
 ```
 ### 1.2 版本控制
 **URL 路径版本化**：
 ```
 /api/v1/members
 /api/v2/members
 ```
 **版本号规则**：
 - 格式：`v{主版本号}`
 - 主版本号递增：不兼容的 API 变更
 - 向后兼容：在同一版本内添加字段
 ### 1.3 响应式 API 设计
 **异步非阻塞**：
 - 使用 Spring WebFlux 实现响应式 API
 - 返回类型：`Mono<T>`（单个对象）、`Flux<T>`（集合）
 - 支持 Server-Sent Events (SSE) 实时推送
 **示例**：
 ```java
 // 单个资源
@GetMapping("/{id}")
 public Mono<Member> getMember(@PathVariable Long id) {
    return memberService.findById(id);
 }
 // 资源集合
@GetMapping
 public Flux<Member> listMembers() {
    return memberService.findAll();
 }
 // SSE 实时推送
@GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
 public Flux<Member> streamMembers() {
    return memberService.streamAll();
 }
 ```
 ---
 ## 二、API 响应格式
 ### 2.1 标准响应结构
 **成功响应**：
 ```json
 {
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "name": "张三",
    "phone": "138****1234"
  },
  "timestamp": "2026-03-08T10:30:00Z"
 }
 ```
 **列表响应**：
 ```json
 {
  "code": 200,
  "message": "success",
  "data": {
    "items": [
      {
        "id": 1,
        "name": "张三"
      },
      {
        "id": 2,
        "name": "李四"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 100,
      "totalPages": 5
    }
  },
  "timestamp": "2026-03-08T10:30:00Z"
 }
 ```
 **错误响应**：
 ```json
 {
  "code": 400,
  "message": "参数验证失败",
  "errors": [
    {
      "field": "phone",
      "message": "手机号格式不正确"
    }
  ],
  "timestamp": "2026-03-08T10:30:00Z"
 }
 ```
 ### 2.2 HTTP 状态码
 | 状态码 | 含义 | 使用场景 |
 |--------|------|----------|
 | 200 OK | 成功 | GET、PUT、PATCH 成功 |
 | 201 Created | 已创建 | POST 成功创建资源 |
 | 204 No Content | 无内容 | DELETE 成功 |
 | 400 Bad Request | 请求错误 | 参数验证失败 |
 | 401 Unauthorized | 未授权 | 未登录或 Token 过期 |
 | 403 Forbidden | 禁止访问 | 权限不足 |
 | 404 Not Found | 未找到 | 资源不存在 |
 | 409 Conflict | 冲突 | 资源已存在 |
 | 422 Unprocessable Entity | 不可处理 | 业务规则验证失败 |
 | 429 Too Many Requests | 请求过多 | 触发限流 |
 | 500 Internal Server Error | 服务器错误 | 系统异常 |
 ### 2.3 数据格式
 **日期时间格式**：
 ```
 ISO 8601: 2026-03-08T10:30:00Z
 日期：2026-03-08
 时间：10:30:00
 ```
 **数字格式**：
 ```
 金额：100.00 (DECIMAL)
 数量：10 (INTEGER)
 比例：0.15 (DECIMAL)
 ```
 **布尔值**：
 ```
 true/false (JSON 原生布尔值)
 ```
 ---
 ## 三、API 接口分类
 ### 3.1 会员管理 API
 #### 3.1.1 创建会员
 ```
 POST /api/v1/members
 ```
 **请求体**：
 ```json
 {
  "phone": "13812341234",
  "name": "张三",
  "gender": 1,
  "birthday": "1990-01-01",
  "fitnessGoal": "增肌"
 }
 ```
 **响应**：
 ```json
 {
  "code": 201,
  "message": "创建成功",
  "data": {
    "id": 1,
    "phone": "138****1234",
    "name": "张三"
  }
 }
 ```
 #### 3.1.2 获取会员详情
 ```
 GET /api/v1/members/{id}
 ```
 **响应**：
 ```json
 {
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "phone": "138****1234",
    "name": "张三",
    "gender": 1,
    "birthday": "1990-01-01",
    "fitnessGoal": "增肌",
    "status": 1,
    "level": 2
  }
 }
 ```
 #### 3.1.3 会员列表查询
 ```
 GET /api/v1/members
 ```
 **查询参数**：
 ```
 ?phone=13812341234&status=1&page=1&size=20&sort=createdAt,desc
 ```
 **响应**：
 ```json
 {
  "code": 200,
  "message": "success",
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 100,
      "totalPages": 5
    }
  }
 }
 ```
 ### 3.2 预约管理 API
 #### 3.2.1 创建预约
 ```
 POST /api/v1/bookings
 ```
 **请求体**：
 ```json
 {
  "slotId": 1,
  "memberId": 1
 }
 ```
 **响应**：
 ```json
 {
  "code": 201,
  "message": "预约成功",
  "data": {
    "id": 1,
    "bookingNo": "BK202603080001",
    "status": 1
  }
 }
 ```
 #### 3.2.2 取消预约
 ```
 DELETE /api/v1/bookings/{id}
 ```
 **响应**：
 ```json
 {
  "code": 204,
  "message": "取消成功"
 }
 ```
 ### 3.3 订阅管理 API
 #### 3.3.1 开通订阅模块
 ```
 POST /api/v1/subscriptions
 ```
 **请求体**：
 ```json
 {
  "moduleCode": "marketing",
  "billingCycle": 1,
  "startDate": "2026-03-08",
  "endDate": "2026-04-07"
 }
 ```
 **响应**：
 ```json
 {
  "code": 201,
  "message": "开通成功",
  "data": {
    "id": 1,
    "subscriptionNo": "SUB202603080001",
    "moduleCode": "marketing",
    "status": 1
  }
 }
 ```
 ---
 ## 四、错误处理
 ### 4.1 错误码规范
 **错误码结构**：
 ```
 业务码 (3 位) + 错误类型码 (2 位) + 具体错误码 (2 位)
 ```
 **示例**：
 ```
 MEM0101 - 会员创建失败
 MEM0102 - 会员手机号已存在
 BOK0201 - 预约失败
 BOK0202 - 预约时段已满
 SUB0301 - 订阅开通失败
 ```
 ### 4.2 全局异常处理
 **控制器建议**：
 ```java
@RestControllerAdvice
 public class GlobalExceptionHandler {
    @ExceptionHandler(ResourceNotFoundException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public Mono<ApiResponse<Void>> handleResourceNotFound(
        ResourceNotFoundException ex) {
        return Mono.just(ApiResponse.error(404, ex.getMessage()));
    }
    @ExceptionHandler(ValidationException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public Mono<ApiResponse<Void>> handleValidationException(
        ValidationException ex) {
        return Mono.just(ApiResponse.error(400, ex.getMessage(), ex.getErrors()));
    }
    @ExceptionHandler(Exception.class)
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    public Mono<ApiResponse<Void>> handleException(Exception ex) {
        log.error("系统异常", ex);
        return Mono.just(ApiResponse.error(500, "系统繁忙，请稍后重试"));
    }
 }
 ```
 ### 4.3 参数验证
 **请求体验证**：
 ```java
 public class CreateMemberRequest {
    @NotBlank(message = "手机号不能为空")
    @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确")
    private String phone;
    @NotBlank(message = "姓名不能为空")
    @Size(min = 1, max = 50, message = "姓名长度不能超过 50 个字符")
    private String name;
    @NotNull(message = "性别不能为空")
    @Min(value = 0, message = "性别值无效")
    @Max(value = 2, message = "性别值无效")
    private Integer gender;
    // getters and setters
 }
 ```
 ---
 ## 五、安全设计
 ### 5.1 认证机制
 **JWT Token 认证**：
 ```
 Authorization: Bearer {token}
 ```
 **Token 结构**：
 ```json
 {
  "sub": "user123",
  "tenantId": 1,
  "storeId": 1,
  "roles": ["ADMIN"],
  "iat": 1709870400,
  "exp": 1709956800
 }
 ```
 ### 5.2 权限控制
 **基于角色的访问控制 (RBAC)**：
 ```java
@PreAuthorize("hasRole('ADMIN')")
@PostMapping
 public Mono<Member> createMember(@RequestBody CreateMemberRequest request) {
    return memberService.create(request);
 }
@PreAuthorize("hasAnyRole('ADMIN', 'COACH')")
@GetMapping("/{id}")
 public Mono<Member> getMember(@PathVariable Long id) {
    return memberService.findById(id);
 }
 ```
 ### 5.3 限流
 **令牌桶限流**：
 ```java
@RateLimiter(name = "apiRateLimiter")
@GetMapping
 public Flux<Member> listMembers() {
    return memberService.findAll();
 }
 ```
 **配置**：
 ```yaml
 resilience4j:
  ratelimiter:
    instances:
      apiRateLimiter:
        limit-for-period: 100  # 每次允许 100 个请求
        limit-refresh-period: 1s  # 每秒刷新
        timeout-duration: 0  # 不等待
 ```
 ---
 ## 六、API 文档
 ### 6.1 OpenAPI 规范
 **使用 Springdoc OpenAPI**：
 ```java
@Bean
 public OpenAPI customOpenAPI() {
    return new OpenAPI()
        .info(new Info()
            .title("健身房管理系统 API")
            .version("v1")
            .description("健身房管理系统 RESTful API 文档"))
        .addSecurityItem(new SecurityRequirement().addList("bearerAuth"))
        .components(new Components()
            .addSecuritySchemes("bearerAuth",
                new SecurityScheme()
                    .type(SecurityScheme.Type.HTTP)
                    .scheme("bearer")
                    .bearerFormat("JWT")));
 }
 ```
 ### 6.2 API 文档访问
 **Swagger UI**：
 ```
 http://localhost:8080/swagger-ui.html
 ```
 **OpenAPI JSON**：
 ```
 http://localhost:8080/v3/api-docs
 ```
 ---
 ## 七、API 版本迁移
 ### 7.1 版本兼容策略
 **向后兼容**：
 - 添加新字段：不影响旧版本
 - 添加新接口：不影响旧版本
 - 扩展枚举值：不影响旧版本
 **不兼容变更**：
 - 删除字段：需要升级版本
 - 修改字段类型：需要升级版本
 - 修改业务逻辑：需要升级版本
 ### 7.2 版本废弃流程
 1. **标记废弃**：在旧版本 API 添加 `@Deprecated` 注解
 2. **通知用户**：通过文档、邮件通知升级
 3. **过渡期**：至少保留 3 个月
 4. **正式下线**：移除旧版本 API
 ---
 ## 八、性能优化
 ### 8.1 分页优化
 **游标分页**：
 ```
 GET /api/v1/members?cursor=eyJpZCI6MTAwfQ==&size=20
 ```
 **优势**：
 - 避免深度分页性能问题
 - 适合大数据量场景
 ### 8.2 字段过滤
 **按需返回字段**：
 ```
 GET /api/v1/members?fields=id,name,phone
 ```
 **优势**：
 - 减少网络传输
 - 提升响应速度
 ### 8.3 缓存策略
 **HTTP 缓存头**：
 ```
 Cache-Control: max-age=3600, public
 ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
 Last-Modified: Wed, 08 Mar 2026 10:30:00 GMT
 ```
 **Redis 缓存**：
 ```java
@Cacheable(value = "members", key = "#id")
 public Mono<Member> findById(Long id) {
    return memberRepository.findById(id);
 }
 ```
 ---
 **文档结束**