SuperAPI AI Directory

resource-modeling

Coding & development

View repository

Updated 10-16 09:31

About this skill

REST Resource Modeling

Reference source: Roy Fielding, "Architectural Styles",REST API Design Best Practices

Applicable Scenarios

  • The first step of API design
  • Abstract business objects into addressable resources
  • Relationship modeling for complex business objects
  • Determine resource granularity

Inapplicable Scenarios

  • RPC-style APIs (no resource modeling needed)
  • GraphQL (model with schema)

Core Principles

1. 资源是名词,不是动词
   ✅ /users
   ❌ /createUser

2. 资源粒度合适
   不要太大(包含太多无关字段)
   不要太细(每个字段都成资源)

3. 资源对应业务对象
   从用户视角看是什么,资源就是什么
   不是从数据库表照搬

4. 资源关系清晰
   通过路径表达从属关系
   /users/123/orders 表示用户 123 的订单

Four Resource Patterns

1. Collection

/resources

GET    /resources         查询列表
POST   /resources         创建新资源

例:
  GET  /users           查询用户列表
  POST /users           创建用户

2. Singleton

/resources/{id}

GET    /resources/{id}    查询单个
PUT    /resources/{id}    完全替换
PATCH  /resources/{id}    部分更新
DELETE /resources/{id}    删除

例:
  GET    /users/123      查询用户 123
  PATCH  /users/123      更新用户 123

3. Sub-resource

/resources/{id}/sub-resources

例:
  /users/123/orders             用户 123 的订单
  /orders/456/items             订单 456 的商品
  /projects/789/members         项目 789 的成员

4. Action Endpoints (Actions)

当无法用状态变更自然表达时使用

/resources/{id}/actions/{action}

例:
  POST /orders/123/cancel       取消订单
  POST /users/123/reset-password 重置密码
  POST /reports/456/export      导出报表

Resource Naming Conventions

✅ 好的:
  - 复数形式(users / orders / products)
  - 小写 + 连字符(reset-password)
  - 名词

❌ 差的:
  - 单数(user / order)
  - 驼峰(ResetPassword)
  - 动词(getUser / createOrder)

Modeling Example

Business: E-commerce order system

业务对象:
  - 用户 User
  - 商品 Product
  - 订单 Order
  - 订单项 OrderItem
  - 支付 Payment
  - 发货 Shipment

资源建模:

集合:
  /users
  /products
  /orders

单资源:
  /users/{id}
  /products/{id}
  /orders/{id}

子资源(用户的):
  /users/{id}/orders            用户的订单
  /users/{id}/addresses         用户的地址

子资源(订单的):
  /orders/{id}/items            订单项
  /orders/{id}/payments         订单支付记录
  /orders/{id}/shipments        发货记录

动作端点:
  POST /orders/{id}/cancel      取消订单
  POST /orders/{id}/refund      申请退款
  POST /orders/{id}/confirm     确认收货

注意:OrderItem 不需要顶层 /order-items
  它只在订单上下文中有意义

Resource Relationship Diagram

erDiagram
    USER ||--o{ ORDER : places
    USER ||--o{ ADDRESS : has
    ORDER ||--|{ ORDER_ITEM : contains
    ORDER ||--o{ PAYMENT : has
    ORDER ||--o{ SHIPMENT : has
    PRODUCT ||--o{ ORDER_ITEM : referenced_by
    
    USER {
        string id PK
        string email
        string name
    }
    ORDER {
        string id PK
        string user_id FK
        string status
        decimal total
    }
    ORDER_ITEM {
        string id PK
        string order_id FK
        string product_id FK
        int quantity
        decimal price
    }

Output Format

## 资源建模:[业务模块]

### 业务对象清单

| 对象 | 业务含义 | 是否独立资源 |
|------|---------|------------|
| User | 用户 | 是(顶层) |
| Order | 订单 | 是(顶层) |
| OrderItem | 订单项 | 否(订单子资源) |

### 资源端点清单

| 资源 | 路径 | 说明 |
|------|------|------|
| 用户集合 | /users | 用户列表和创建 |
| 单用户 | /users/{id} | 用户详情和修改 |
| 用户订单 | /users/{id}/orders | 某用户的订单 |
| 订单集合 | /orders | 全部订单 |
| 单订单 | /orders/{id} | 订单详情 |
| 订单项 | /orders/{id}/items | 订单内的商品 |
| 取消订单 | POST /orders/{id}/cancel | 动作端点 |

### 资源关系图

[Mermaid ER 图]

### 关键决策

- OrderItem 不做顶层资源(不独立有意义)
- 用户地址作为子资源 /users/{id}/addresses
- 取消订单用动作端点(不是 PATCH status)

Workflow

1. 列出业务对象
2. 判断哪些是顶层资源
3. 判断哪些是子资源(不独立)
4. 列出资源关系(一对多 / 多对多)
5. 命名资源(复数 + 小写)
6. 识别需要动作端点的场景
7. 画 ER 关系图
8. 输出资源端点清单
9. 转交 endpoint-design 设计具体端点

Quality Self-check

□ 资源是名词不是动词
□ 复数命名一致
□ 小写 + 连字符
□ 子资源是否真的不独立
□ 是否避免了过深嵌套(不超过 3 层)
□ 动作端点是否真的无法用 CRUD 表达
□ ER 关系图是否完整

Common Pitfalls

  1. Copying directly from database tables——every table is a top-level resource
  2. Resources are verbs——/getUser / /createOrder
  3. Nesting too deep——/users/123/orders/456/items/789/refunds/0
  4. Forcing CRUD——/orders/{id} PATCH {status: "cancelled"} is not as good as /orders/{id}/cancel
  5. Making sub-resources independent——/order-items as a top-level resource (meaningless detached from the order)
  6. Chaotic naming——mixed singular/plural / mixed casing

Supporting Templates

  • templates/resource-model-template.md — Resource modeling + ER diagram template

Collaboration with Other Skills

上游:
  product-manager 的业务实体清单
  database-engineer 的实体关系(参考但不照搬)

下游:
  endpoint-design → 设计每个资源的端点
  request-response → 设计字段