Wild Workouts Go DDD 示例项目中的训练API接口详解

项目背景

Wild Workouts是一个基于领域驱动设计(DDD)理念构建的Go语言健身应用示例项目。该项目展示了如何在实际应用中运用DDD原则，其中训练管理模块是其核心功能之一。本文将重点解析该项目的训练API接口设计。

API概览

训练API提供了完整的训练管理功能，包括：

1. 训练信息查询
2. 创建新训练
3. 取消训练
4. 重新安排训练时间
5. 训练时间调整的请求与审批流程

接口详细解析

1. 获取训练列表

/trainings:
  get:
    operationId: getTrainings

功能：获取当前用户的训练列表

响应：返回一个包含多个训练对象的JSON数组，每个训练对象包含训练ID、用户信息、备注、时间等详细信息

2. 创建新训练

/trainings:
  post:
    operationId: createTraining

请求体：需要提供训练时间和备注信息

特点：采用JWT Bearer Token进行身份验证，确保只有认证用户才能创建训练

3. 取消训练

/trainings/{trainingUUID}:
  delete:
    operationId: cancelTraining

参数：通过路径参数指定要取消的训练UUID

业务规则：后端会校验训练是否可以被取消（基于canBeCancelled字段）

4. 训练时间调整相关接口

项目设计了完整的时间调整流程：

1. 请求重新安排：用户发起时间调整请求
2. 批准重新安排：教练或管理员批准调整
3. 拒绝重新安排：教练或管理员拒绝调整

/trainings/{trainingUUID}/reschedule:
  put:
    operationId: rescheduleTraining

/trainings/{trainingUUID}/request-reschedule:
  put:
    operationId: requestRescheduleTraining

/trainings/{trainingUUID}/approve-reschedule:
  put:
    operationId: approveRescheduleTraining

/trainings/{trainingUUID}/reject-reschedule:
  put:
    operationId: rejectRescheduleTraining

数据结构设计

训练对象(Training)

Training:
  type: object
  required: [uuid, user, userUuid, notes, time, canBeCancelled, moveRequiresAccept]
  properties:
    uuid: string
    user: string
    userUuid: string
    notes: string
    time: string(date-time)
    canBeCancelled: boolean
    moveRequiresAccept: boolean
    proposedTime: string(date-time)
    moveProposedBy: string

关键字段说明：

• canBeCancelled：标识该训练是否可以被取消（基于业务规则）
• moveRequiresAccept：标识时间调整是否需要审批
• proposedTime：当训练时间被请求调整时，存储提议的新时间
• moveProposedBy：记录谁发起了时间调整请求

错误处理

Error:
  type: object
  required: [slug, message]
  properties:
    slug: string
    message: string

采用标准的错误响应格式，包含错误代码(slug)和错误信息(message)，便于客户端统一处理。

安全设计

所有API端点都采用JWT Bearer Token进行保护：

securitySchemes:
  bearerAuth:
    type: http
    scheme: bearer
    bearerFormat: JWT

领域驱动设计体现

从API设计中可以看到明显的DDD痕迹：

1. 明确的领域边界：训练管理作为独立的边界上下文
2. 丰富的领域模型：训练对象包含业务状态和行为（能否取消、是否需要审批等）
3. 业务流程显式化：时间调整的请求-审批流程被明确建模为API操作

最佳实践

1. RESTful设计：合理使用HTTP方法和状态码
2. 资源导向：以训练为核心资源组织API
3. 幂等性设计：PUT操作保证幂等性
4. 版本控制：OpenAPI规范明确定义了API版本

总结

Wild Workouts项目的训练API设计展示了如何将复杂的业务需求转化为清晰的API契约。通过分析这个设计，我们可以学习到：

1. 如何用API表达业务规则和流程
2. DDD概念在API设计中的实际应用
3. 健身领域特定需求的API建模方法
4. 生产级API的安全和错误处理设计

这种设计既满足了功能性需求，又保持了良好的扩展性，是学习API设计和DDD实践的优秀范例。