architect_data-api-design

数据模型和API设计方法论，包含ERD设计、数据字典、RESTful API规范

不碰外部（只输出文字）无严重或高危命中hashgraph-online/awesome-codex-plugins

它会碰到什么

扫了多少1 个文本文件，8 KB

它会碰到什么不碰外部（只输出文字）

命中总数0 处

命中统计严重 0 · 高 0 · 中 0 · 低 0

这一栏是扫描器报的事实，不是结论。命中多不等于有毒（安全工具、规则库、示例脚本本来就会包含危险写法），命中少也不等于干净。它和你手上的凭据、文件、网络有什么关系，需要你自己看。

技能内容

数据模型与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() | 主键 |

索引：

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

Post 表

| 字段 | 类型 | 约束 | 默认值 | 说明 |

|------|------|------|--------|------|

| id | UUID | PK | uuid_generate_v4() | 主键 |

索引：

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

5. 数据类型选择

|----------|----------|------------|-------|---------|

API设计

1. API规范选择

| 规范 | 适用场景 | 优点 | 缺点 |

|------|----------|------|------|

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

2. RESTful API设计原则

资源命名

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

HTTP方法

| 方法 | 用途 | 示例 | 幂等性 |

|------|------|------|--------|

| GET | 获取资源 | GET /users | 是 |

| PUT | 完整更新 | PUT /users/123 | 是 |

URL设计

| 操作 | 方法 | 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接口列表

| 模块 | 方法 | 路径 | 描述 | 认证 | 权限 |

|------|------|------|------|------|------|

| 认证 | | | | | |

| | GET | /api/v1/auth/me | 获取当前用户 | 是 | - |

| 用户 | | | | | |

| | GET | /api/v1/users/:id | 获取用户详情 | 是 | - |

| 文章 | | | | | |

| | GET | /api/v1/posts | 获取文章列表 | 否 | - |

| | GET | /api/v1/posts/:id | 获取文章详情 | 否 | - |

输出要求

完成数据模型和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 响应格式

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