data-api-design
starsforks
How to install data-api-design?
echovic/boss-skill/data-api-design
$npx -y skills add echoVic/boss-skill --skill data-api-design数据模型和API设计方法论，包含ERD设计、数据字典、RESTful API规范
SKILL.md
| 1 | # 数据模型与API设计方法论 |
| 2 | |
| 3 | ## 适用场景 |
| 4 | |
| 5 | 在系统架构确定后，需要设计： |
| 6 | - 数据库表结构和关系 |
| 7 | - 数据字典和约束 |
| 8 | - API接口规范 |
| 9 | - 请求/响应格式 |
| 10 | |
| 11 | ## 数据模型设计 |
| 12 | |
| 13 | ### 1. 实体识别 |
| 14 | |
| 15 | 从PRD中识别核心实体（名词）： |
| 16 | |
| 17 | **示例**： |
| 18 | - 用户系统：User（用户）、Role（角色）、Permission（权限） |
| 19 | - 博客系统：User（用户）、Post（文章）、Comment（评论）、Tag（标签） |
| 20 | - 电商系统：User（用户）、Product（商品）、Order（订单）、OrderItem（订单项） |
| 21 | |
| 22 | ### 2. 关系识别 |
| 23 | |
| 24 | 确定实体之间的关系： |
| 25 | |
| 26 | | 关系类型 | 说明 | 示例 | |
| 27 | |----------|------|------| |
| 28 | | **一对一 (1:1)** | 一个A对应一个B | User - Profile | |
| 29 | | **一对多 (1:N)** | 一个A对应多个B | User - Post | |
| 30 | | **多对多 (M:N)** | 多个A对应多个B | Post - Tag | |
| 31 | |
| 32 | **关系表示**： |
| 33 | - `||--o{`: 一对多 |
| 34 | - `||--||`: 一对一 |
| 35 | - `}o--o{`: 多对多 |
| 36 | |
| 37 | ### 3. 实体关系图 (ERD) |
| 38 | |
| 39 | 使用 Mermaid 绘制 ERD： |
| 40 | |
| 41 | ```mermaid |
| 42 | erDiagram |
| 43 | User ||--o{ Post : creates |
| 44 | User ||--o{ Comment : writes |
| 45 | Post ||--o{ Comment : has |
| 46 | Post }o--o{ Tag : has |
| 47 | |
| 48 | User { |
| 49 | uuid id PK |
| 50 | string email UK |
| 51 | string name |
| 52 | string passwordHash |
| 53 | enum role |
| 54 | datetime createdAt |
| 55 | datetime updatedAt |
| 56 | } |
| 57 | |
| 58 | Post { |
| 59 | uuid id PK |
| 60 | uuid authorId FK |
| 61 | string title |
| 62 | text content |
| 63 | enum status |
| 64 | datetime publishedAt |
| 65 | datetime createdAt |
| 66 | datetime updatedAt |
| 67 | } |
| 68 | |
| 69 | Comment { |
| 70 | uuid id PK |
| 71 | uuid postId FK |
| 72 | uuid userId FK |
| 73 | text content |
| 74 | datetime createdAt |
| 75 | } |
| 76 | |
| 77 | Tag { |
| 78 | uuid id PK |
| 79 | string name UK |
| 80 | } |
| 81 | ``` |
| 82 | |
| 83 | ### 4. 数据字典 |
| 84 | |
| 85 | 为每个表定义详细的字段信息： |
| 86 | |
| 87 | #### User 表 |
| 88 | |
| 89 | | 字段 | 类型 | 约束 | 默认值 | 说明 | |
| 90 | |------|------|------|--------|------| |
| 91 | | id | UUID | PK | uuid_generate_v4() | 主键 | |
| 92 | | email | VARCHAR(255) | UNIQUE, NOT NULL | - | 邮箱，用于登录 | |
| 93 | | name | VARCHAR(100) | NOT NULL | - | 用户名 | |
| 94 | | passwordHash | VARCHAR(255) | NOT NULL | - | 密码哈希（bcrypt） | |
| 95 | | role | ENUM('user', 'admin') | NOT NULL | 'user' | 用户角色 | |
| 96 | | createdAt | TIMESTAMP | NOT NULL | NOW() | 创建时间 | |
| 97 | | updatedAt | TIMESTAMP | NOT NULL | NOW() | 更新时间 | |
| 98 | |
| 99 | **索引**： |
| 100 | - `idx_user_email`: email（唯一索引，用于登录查询） |
| 101 | - `idx_user_role`: role（用于角色筛选） |
| 102 | |
| 103 | #### Post 表 |
| 104 | |
| 105 | | 字段 | 类型 | 约束 | 默认值 | 说明 | |
| 106 | |------|------|------|--------|------| |
| 107 | | id | UUID | PK | uuid_generate_v4() | 主键 | |
| 108 | | authorId | UUID | FK, NOT NULL | - | 作者ID，外键关联User.id | |
| 109 | | title | VARCHAR(200) | NOT NULL | - | 文章标题 | |
| 110 | | content | TEXT | NOT NULL | - | 文章内容 | |
| 111 | | status | ENUM('draft', 'published', 'archived') | NOT NULL | 'draft' | 文章状态 | |
| 112 | | publishedAt | TIMESTAMP | NULL | - | 发布时间 | |
| 113 | | createdAt | TIMESTAMP | NOT NULL | NOW() | 创建时间 | |
| 114 | | updatedAt | TIMESTAMP | NOT NULL | NOW() | 更新时间 | |
| 115 | |
| 116 | **索引**： |
| 117 | - `idx_post_author`: authorId（用于查询用户的文章） |
| 118 | - `idx_post_status`: status（用于筛选状态） |
| 119 | - `idx_post_published`: publishedAt（用于按发布时间排序） |
| 120 | |
| 121 | ### 5. 数据类型选择 |
| 122 | |
| 123 | | 数据类型 | 使用场景 | PostgreSQL | MySQL | MongoDB | |
| 124 | |----------|----------|------------|-------|---------| |
| 125 | | **主键** | 唯一标识 | UUID, SERIAL | INT AUTO_INCREMENT, UUID | ObjectId | |
| 126 | | **字符串** | 短文本 | VARCHAR(n) | VARCHAR(n) | String | |
| 127 | | **长文本** | 文章内容 | TEXT | TEXT | String | |
| 128 | | **整数** | 数量、年龄 | INTEGER, BIGINT | INT, BIGINT | Number | |
| 129 | | **小数** | 价格、评分 | DECIMAL(p,s) | DECIMAL(p,s) | Number | |
| 130 | | **布尔** | 是否标志 | BOOLEAN | TINYINT(1) | Boolean | |
| 131 | | **日期时间** | 时间戳 | TIMESTAMP | DATETIME | Date | |
| 132 | | **枚举** | 固定选项 | ENUM | ENUM | String | |
| 133 | | **JSON** | 灵活数据 | JSONB | JSON | Object | |
| 134 | |
| 135 | **推荐**： |
| 136 | - **主键**：使用 UUID 而非自增ID（避免暴露数据量、分布式友好） |
| 137 | - **时间戳**：使用 TIMESTAMP WITH TIME ZONE（时区友好） |
| 138 | - **枚举**：使用 ENUM 而非字符串（类型安全、节省空间） |
| 139 | - **JSON**：PostgreSQL 使用 JSONB（支持索引和查询） |
| 140 | |
| 141 | ## API设计 |
| 142 | |
| 143 | ### 1. API规范选择 |
| 144 | |
| 145 | | 规范 | 适用场景 | 优点 | 缺点 | |
| 146 | |------|----------|------|------| |
| 147 | | **RESTful** | 通用场景、CRUD操作 | 简单、标准、易理解 | 过度获取、多次请求 | |
| 148 | | **GraphQL** | 复杂查询、多端适配 | 按需获取、类型安全 | 学习曲线、缓存复杂 | |
| 149 | | **gRPC** | 微服务、高性能 | 性能高、类型安全 | 浏览器支持差 | |
| 150 | |
| 151 | **本项目推荐**：RESTful（除非有特殊需求） |
| 152 | |
| 153 | ### 2. RESTful API设计原则 |
| 154 | |
| 155 | #### 资源命名 |
| 156 | |
| 157 | - **使用名词**：`/users`, `/posts`, `/comments`（不是 `/getUsers`, `/createPost`） |
| 158 | - **使用复数**：`/users`（不是 `/user`） |
| 159 | - **使用小写**：`/users`（不是 `/Users`） |
| 160 | - **使用连字符**：`/order-items`（不是 `/orderItems` 或 `/order_items`） |
| 161 | |
| 162 | #### HTTP方法 |
| 163 | |
| 164 | | 方法 | 用途 | 示例 | 幂等性 | |
| 165 | |------|------|------|--------| |
| 166 | | GET | 获取资源 | `GET /users` | 是 | |
| 167 | | POST | 创建资源 | `POST /users` | 否 | |
| 168 | | PUT | 完整更新 | `PUT /users/123` | 是 | |
| 169 | | PATCH | 部分更新 | `PATCH /users/123` | 否 | |
| 170 | | DELETE | 删除资源 | `DELETE /users/123` | 是 | |
| 171 | |
| 172 | #### URL设计 |
| 173 | |
| 174 | | 操作 | 方法 | URL | 说明 | |
| 175 | |------|------|-----|------| |
| 176 | | 获取列表 | GET | `/api/v1/users` | 支持分页、筛选、排序 | |
| 177 | | 获取详情 | GET | `/api/v1/users/:id` | 返回单个资源 | |
| 178 | | 创建 | POST | `/api/v1/users` | 请求体包含资源数据 | |
| 179 | | 完整更新 | PUT | `/api/v1/users/:id` | 替换整个资源 | |
| 180 | | 部分更新 | PATCH | `/api/v1/users/:id` | 只更新指定字段 | |
| 181 | | 删除 | DELETE | `/api/v1/users/:id` | 删除资源 | |
| 182 | |
| 183 | **嵌套资源**： |
| 184 | - `GET /api/v1/users/:userId/posts` - 获取用户的文章 |
| 185 | - `POST /api/v1/posts/:postId/comments` - 为文章创建评论 |
| 186 | |
| 187 | **查询参数**： |
| 188 | - 分页：`?page=1&limit=20` |
| 189 | - 筛选：`?status=published&author=123` |
| 190 | - 排序：`?sort=-createdAt`（-表示降序） |
| 191 | - 搜索：`?q=keyword` |
| 192 | |
| 193 | ### 3. 请求/响应格式 |
| 194 | |
| 195 | #### 成功响应 |
| 196 | |
| 197 | **单个资源**： |
| 198 | ```json |
| 199 | { |
| 200 | "success": true, |
| 201 | "data": { |
| 202 | "id": "123", |
| 203 | "name": "John Doe", |
| 204 | "email": "john@example.com" |
| 205 | } |
| 206 | } |
| 207 | `` |
People who liked this also viewed
6 picksType
- azure-storageAzure Storage Services including Blob Storage, File Shares, Queue Storage, Table Storage, and Data Lake. Answers questions about storage access tiers (hot, cool, cold, archive), when to use each tier,SkillsJul 2026
- supabase-postgres-best-practicesPostgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.SkillsJul 2026
- supabaseUse when doing ANY task involving Supabase. Triggers: Supabase products (Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron, Queues); client libraries and SSR integrations (supabase-js, SkillsJul 2026
- convex-quickstartCreates or adds Convex to an app. Use for new Convex projects, npm create convex@latest, frontend setup, env vars, or the first npx convex dev run.SkillsJul 2026
- convex-performance-auditAudits Convex performance for reads, subscriptions, write contention, and function limits. Use for slow features, insights findings, OCC conflicts, or read amplification.SkillsJul 2026
- convex-setup-authSets up Convex auth, identity mapping, and access control. Use for login, auth providers, users tables, protected functions, or roles in a Convex app.SkillsJul 2026
