mini-starter/docs/architecture/api-design-integration.md

API设计和集成

版本信息

版本	日期	描述	作者
2.4	2025-09-20	与主架构文档版本一致	Winston

API集成策略

• API集成策略: 保持现有RESTful API设计，增强OpenAPI文档
• 认证: JWT Bearer Token，保持现有认证机制
• 版本控制: 使用v1前缀 (/api/v1/)，保持向后兼容

OpenAPI规范

openapi: 3.0.0
info:
  title: D8D Starter API
  version: 1.0.0
  description: D8D Starter项目RESTful API文档
servers:
  - url: http://localhost:3000/api/v1
    description: 本地开发环境
  - url: https://api.example.com/api/v1
    description: 生产环境

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        username:
          type: string
        email:
          type: string
          nullable: true
        roles:
          type: array
          items:
            $ref: '#/components/schemas/Role'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    Role:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        permissions:
          type: array
          items:
            type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    PaginatedUsers:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/User'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Pagination:
      type: object
      properties:
        total:
          type: integer
        current:
          type: integer
        pageSize:
          type: integer
        totalPages:
          type: integer

security:
  - BearerAuth: []

API端点示例

用户管理端点:

• 方法: GET
• 端点: /api/v1/users
• 用途: 获取用户分页列表
• 集成: 使用通用CRUD服务，支持搜索和过滤

请求示例:

{
  "page": 1,
  "pageSize": 10,
  "keyword": "搜索词",
  "sortBy": "createdAt",
  "sortOrder": "DESC"
}

响应示例:

{
  "data": [
    {
      "id": 1,
      "email": "user@example.com",
      "roles": [{"id": 1, "name": "admin"}]
    }
  ],
  "pagination": {
    "total": 100,
    "current": 1,
    "pageSize": 10
  }
}

文件管理端点:

• 方法: POST
• 端点: /api/v1/files/upload-policy
• 用途: 生成文件上传策略和预签名URL
• 集成: 使用MinIO服务，支持分段上传和大文件处理

请求示例:

{
  "name": "example.pdf",
  "type": "application/pdf",
  "size": 1048576,
  "description": "示例文件"
}

响应示例:

{
  "file": {
    "id": 123,
    "name": "example.pdf",
    "path": "user-1/uuid-example.pdf",
    "size": 1048576,
    "type": "application/pdf",
    "uploadUserId": 1,
    "uploadTime": "2025-09-19T10:30:00.000Z"
  },
  "uploadPolicy": {
    "x-amz-algorithm": "AWS4-HMAC-SHA256",
    "x-amz-credential": "minioadmin/20250919/us-east-1/s3/aws4_request",
    "x-amz-date": "20250919T103000Z",
    "policy": "base64-encoded-policy",
    "x-amz-signature": "signature",
    "host": "https://minio.example.com",
    "key": "user-1/uuid-example.pdf",
    "bucket": "d8dai"
  }
}