architect/data-api-design

数据模型与API设计方法论

适用场景

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

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

数据模型设计

1. 实体识别

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

示例：

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

2. 关系识别

确定实体之间的关系：

关系表示：

• ||--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 表

索引：

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

Post 表

索引：

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

5. 数据类型选择

推荐：

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

API设计

1. API规范选择

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

2. RESTful API设计原则

资源命名

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

HTTP方法

URL设计

嵌套资源：

• GET /api/v1/users/:userId/posts - 获取用户的文章
• POST /api/v1/posts/:postId/comments - 为文章创建评论

查询参数：

• 分页：?page=1&limit=20
• 筛选：?status=published&author=123
• 排序：?sort=-createdAt（-表示降序）
• 搜索：?q=keyword

3. 请求/响应格式

成功响应

单个资源：

{
  "success": true,
  "data": {
    "id": "123",
    "name": "John Doe",
    "email": "john@example.com"
  }
}

资源列表：

{
  "success": true,
  "data": [
    { "id": "1", "name": "Item 1" },
    { "id": "2", "name": "Item 2" }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}

错误响应

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "邮箱格式不正确",
    "details": [
      {
        "field": "email",
        "message": "必须是有效的邮箱地址"
      }
    ]
  }
}

错误码：

• VALIDATION_ERROR: 验证错误（400）
• UNAUTHORIZED: 未认证（401）
• FORBIDDEN: 无权限（403）
• NOT_FOUND: 资源不存在（404）
• CONFLICT: 资源冲突（409，如邮箱已存在）
• INTERNAL_ERROR: 服务器错误（500）

4. 认证和授权

认证方案

JWT (推荐)：

Authorization: Bearer <token>

请求头：

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123"
}

响应：

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "123",
      "name": "John Doe",
      "email": "john@example.com"
    }
  }
}

授权模型

RBAC (基于角色)：

enum Role {
  USER = 'user',
  ADMIN = 'admin'
}

// 中间件检查
if (user.role !== Role.ADMIN) {
  throw new ForbiddenError();
}

5. API接口列表

输出要求

完成数据模型和API设计后，应输出以下内容（通常作为架构文档的第4-5章）：

## 4. 数据模型

### 4.1 实体关系图 (ERD)

[Mermaid ERD]

### 4.2 数据字典

#### User 表

[字段表格]

#### Post 表

[字段表格]

---

## 5. API 设计

### 5.1 API 规范

- **风格**：RESTful
- **版本**：URL 前缀 `/api/v1`
- **认证**：Bearer Token (JWT)
- **格式**：JSON

### 5.2 接口列表

[接口表格]

### 5.3 响应格式

[成功响应示例]
[错误响应示例]

关键原则

1. 规范化：遵循数据库范式，避免冗余
2. 类型安全：使用强类型（UUID、ENUM）
3. RESTful：遵循REST原则，资源导向
4. 一致性：命名、格式、错误码保持一致
5. 文档化：每个字段、每个接口都有清晰说明

常见误区

❌ 使用动词：/getUsers, /createPost（应该用HTTP方法表示动作） ❌ 过度嵌套：/users/:id/posts/:id/comments/:id（最多2层） ❌ 暴露实现：/api/getUserFromDatabase（暴露内部实现） ❌ 不一致：有的用复数有的用单数，有的驼峰有的下划线