/data-api-design

name: architect/data-api-design
description: 数据模型和API设计方法论，包含ERD设计、数据字典、RESTful API规范
version: 1.0.0
agent: architect
type: methodology
user-invocable: false
agent-invocable: true
dependencies: []
triggers:
- 架构设计完成后
- 需要设计数据模型时
- 需要定义API接口时
  metadata:
  internal: true

数据模型与API设计方法论

适用场景

在系统架构确定后，需要设计：

• 数据库表结构和关系
• 数据字典和约束
• API接口规范
• 请求/响应格式

数据模型设计

1. 实体识别

从PRD中识别核心实体（名词）：

**示例**：

• 用户系统：User（用户）、Role（角色）、Permission（权限）
• 博客系统：User（用户）、Post（文章）、Comment（评论）、Tag（标签）
• 电商系统：User（用户）、Product（商品）、Order（订单）、OrderItem（订单项）

2. 关系识别

确定实体之间的关系：

| 关系类型 | 说明 | 示例 | | ---------------- | -------------- | -------------- | | **一对一 (1:1)** | 一个A对应一个B | User - Profile | | **一对多 (1:N)** | 一个A对应多个B | User - Post | | **多对多 (M:N)** | 多个A对应多个B | Post - Tag |

**关系表示**：

• `||--o{`: 一对多
• `||--||`: 一对一
• `}o--o{`: 多对多

3. 实体关系图 (ERD)

使用 Mermaid 绘制 ERD：

erDiagram
    User ||--o{ Post : creates
    User ||--o{ Comment : writes
    Post ||--o{ Comment : has
    Post }o--o{ Tag : has

    User {
        uuid id PK
        string email UK
        string name
        string passwordHash
        enum role
        datetime createdAt
        datetime updatedAt
    }

    Post {
        uuid id PK
        uuid authorId FK
        string title
        text content
        enum status
        datetime publishedAt
        datetime createdAt
        datetime updatedAt
    }

    Comment {
        uuid id PK
        uuid postId FK
        uuid userId FK
        text content
        datetime createdAt
    }

    Tag {
        uuid id PK
        string name UK
    }

4. 数据字典

为每个表定义详细的字段信息：

User 表

| 字段 | 类型 | 约束 | 默认值 | 说明 | | ------------ | --------------------- | ---------------- | ------------------ | ------------------ | | id | UUID | PK | uuid_generate_v4() | 主键 | | email | VARCHAR(255) | UNIQUE, NOT NULL | - | 邮箱，用于登录 | | name | VARCHAR(100) | NOT NULL | - | 用户名 | | passwordHash | VARCHAR(255) | NOT NULL | - | 密码哈希（bcrypt） | | role | ENUM('user', 'admin') | NOT NULL | 'user' | 用户角色 | | createdAt | TIMESTAMP | NOT NULL | NOW() | 创建时间 | | updatedAt | TIMESTAMP | NOT NULL | NOW() | 更新时间 |

**索引**：

• `idx_user_email`: email（唯一索引，用于登录查询）
• `idx_user_role`: role（用于角色筛选）

Post 表

| 字段 | 类型 | 约束 | 默认值 | 说明 | | ----------- | -------------------------------------- | ------------ | ------------------ | ----------------------- | | id | UUID | PK | uuid_generate_v4() | 主键 | | authorId | UUID | FK, NOT NULL | - | 作者ID，外键关联User.id | | title | VARCHAR(200) | NOT NULL | - | 文章标题 | | content | TEXT | NOT NULL | - | 文章内容 | | status | ENUM('draft', 'published', 'archived') | NOT NULL | 'draft' | 文章状态 | | publishedAt | TIMESTAMP | NULL | - | 发布时间 | | createdAt | TIMESTAMP | NOT NULL | NOW() | 创建时间 | | updatedAt | TIMESTAMP | NOT NULL | NOW() | 更新时间 |

**索引**：

• `idx_post_author`: authorId（用于查询用户的文章）
• `idx_post_status`: status（用于筛选状态）
• `idx_post_published`: publishedAt（用于按发布时间排序）

5. 数据类型选择

| 数据类型 | 使用场景 | PostgreSQL | MySQL | MongoDB | | ------------ | ---------- | --------------- | ------------------------ | -------- | | **主键** | 唯一标识 | UUID, SERIAL | INT AUTO_INCREMENT, UUID | ObjectId | | **字符串** | 短文本 | VARCHAR(n) | VARCHAR(n) | String | | **长文本** | 文章内容 | TEXT | TEXT | String | | **整数** | 数量、年龄 | INTEGER, BIGINT | INT, BIGINT | Number | | **小数** | 价格、评分 | DECIMAL(p,s) | DECIMAL(p,s) | Number | | **布尔** | 是否标志 | BOOLEAN | TINYINT(1) | Boolean | | **日期时间** | 时间戳 | TIMESTAMP | DATETIME | Date | | **枚举** | 固定选项 | ENUM | ENUM | String | | **JSON** | 灵活数据 | JSONB | JSON | Object |

**推荐**：

• **主键**：使用 UUID 而非自增ID（避免暴露数据量、分布式友好）
• **时间戳**：使用 TIMESTAMP WITH TIME ZONE（时区友好）
• **枚举**：使用 ENUM 而非字符串（类型安全、节省空间）
• **JSON**：PostgreSQL 使用 JSONB（支持索引和查询）

API设计

1. API规范选择

| 规范 | 适用场景 | 优点 | 缺点 | | ----------- | ------------------ | ------------------ | ------------------ | | **RESTful** | 通用场景、CRUD操作 | 简单、标准、易理解 | 过度获取、多次请求 | | **GraphQL** | 复杂查询、多端适配 | 按需获取、类型安全 | 学习曲线、缓存复杂 | | **gRPC** | 微服务、高性能 | 性能高、类型安全 | 浏览器支持差 |

**本项目推荐**：RESTful（除非有特殊需求）

2. RESTful API设计原则

资源命名

• **使用名词**：`/users`, `/posts`, `/comments`（不是 `/getUsers`, `/createPost`）
• **使用复数**：`/users`（不是 `/user`）
• **使用小写**：`/users`（不是 `/Users`）
• **使用连字符**：`/order-items`（不是 `/orderItems` 或 `/order_items`）

HTTP方法

| 方法 | 用途 | 示例 | 幂等性 | | ------ | -------- | ------------------- | ------ | | GET | 获取资源 | `GET /users` | 是 | | POST | 创建资源 | `POST /users` | 否 | | PUT | 完整更新 | `PUT /users/123` | 是 | | PATCH | 部分更新 | `PATCH /users/123` | 否 | | DELETE | 删除资源 | `DELETE /users/123` | 是 |

URL设计

| 操作 | 方法 | URL