phase-4-api

阶段 4：API 设计/实现 + 零脚本 QA

后端 API 实现与无脚本 QA

目的

实现能够存储和检索数据的后端 API。使用结构化日志而非测试脚本进行验证。

本阶段要做什么

1. API 设计：定义端点、请求和响应
2. API 实现：编写实际的后端代码
3. 零脚本 QA：基于日志进行验证

交付物

docs/02-design/
└── api-spec.md             # API specification

src/api/                    # API implementation
├── routes/
├── controllers/
└── services/

docs/03-analysis/
└── api-qa.md               # QA results

PDCA 应用

• 计划：定义所需的 API 列表
• 设计：设计端点、请求和响应
• 执行：实现 API
• 检查：使用零脚本 QA 进行验证
• 改进：修复错误并进入阶段 5

分级应用

级别	应用方法
入门级	跳过本阶段（无 API）
动态级	使用 bkend.ai BaaS（见下文）
企业级	直接实现 API

动态级：bkend.ai BaaS API 实现

步骤 1：MCP 设置

claude mcp add bkend --transport http https://api.bkend.ai/mcp

步骤 2：表设计（通过 MCP 工具）

自然语言请求：“创建一个 users 表，包含 name（必填）、email（必填、唯一）和 age 字段” -> 自动调用 MCP backend_table_create

步骤 3：服务 API 集成

方法	端点	描述
GET	/v1/data/{table}	列表（筛选、排序、分页）
POST	/v1/data/{table}	创建数据
GET	/v1/data/{table}/{id}	获取单条数据
PATCH	/v1/data/{table}/{id}	部分更新
DELETE	/v1/data/{table}/{id}	删除

必需的请求头：x-project-id、x-environment、Authorization

步骤 4：身份验证实现

参考 MCP 工具 3_howto_implement_auth 和 6_code_examples_auth

步骤 5：零脚本 QA

• 在浏览器 DevTools 的 Network 标签页中检查 bkend REST API 调用日志
• 通过响应代码/响应正文验证 API 行为

什么是零脚本 QA？

Instead of writing test scripts, validate with structured debug logs

[API] POST /api/users
[INPUT] { "email": "[email protected]", "name": "Test" }
[PROCESS] Email duplicate check → Passed
[PROCESS] Password hash → Complete
[PROCESS] DB save → Success
[OUTPUT] { "id": 1, "email": "[email protected]" }
[RESULT] ✅ Success

Advantages:
- Save test code writing time
- See actual behavior with your eyes
- Easy debugging

RESTful API 原则

什么是 REST？

REpresentational State Transfer（表述性状态转移）——一种用于设计 Web 服务的架构风格。

6 项核心原则

原则	描述	示例
1. 客户端-服务端	分离客户端与服务端的关注点	UI ↔ 数据存储相互分离
2. 无状态	每个请求相互独立，服务端不存储客户端状态	每个请求都包含身份验证令牌
3. 可缓存	响应必须注明是否可缓存	Cache-Control 请求头
4. 统一接口	通过一致的接口进行交互	详见下文
5. 分层系统	允许采用分层系统架构	负载均衡器、代理
6. 按需代码	（可选）服务端可以向客户端发送代码	JavaScript 传输

统一接口详解

RESTful API 的核心是统一接口。

1. 基于资源的 URL

✅ Good (nouns, plural)
GET    /users          # User list
GET    /users/123      # Specific user
POST   /users          # Create user
PUT    /users/123      # Update user
DELETE /users/123      # Delete user

❌ Bad (using verbs)
GET    /getUsers
POST   /createUser
POST   /deleteUser/123

2. HTTP 方法含义

方法	用途	幂等	安全
GET	读取	✅	✅
POST	创建	❌	❌
PUT	完整更新	✅	❌
PATCH	部分更新	❌	❌
DELETE	删除	✅	❌

幂等：即使请求多次，结果也相同 安全：不会更改服务端状态

3. HTTP 状态码

2xx Success
├── 200 OK              # Success (read, update)
├── 201 Created         # Creation success
└── 204 No Content      # Success but no response body (delete)

4xx Client Error
├── 400 Bad Request     # Invalid request (validation failure)
├── 401 Unauthorized    # Authentication required
├── 403 Forbidden       # No permission
├── 404 Not Found       # Resource not found
└── 409 Conflict        # Conflict (duplicate, etc.)

5xx Server Error
├── 500 Internal Error  # Internal server error
└── 503 Service Unavailable  # Service unavailable

4. 一致的响应格式

// Success response
{
  "data": {
    "id": 123,
    "email": "[email protected]",
    "name": "John Doe"
  },
  "meta": {
    "timestamp": "2026-01-08T10:00:00Z"
  }
}

// Error response
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email format is invalid.",
    "details": [
      { "field": "email", "message": "Please enter a valid email" }
    ]
  }
}

// List response (pagination)
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}

URL 设计规则

1. Use lowercase
   ✅ /users/123/orders
   ❌ /Users/123/Orders

2. Use hyphens (-), avoid underscores (_)
   ✅ /user-profiles
   ❌ /user_profiles

3. Express hierarchical relationships
   ✅ /users/123/orders/456

4. Filtering via query parameters
   ✅ /users?status=active&sort=created_at
   ❌ /users/active/sort/created_at

5. Version management
   ✅ /api/v1/users
   ✅ Header: Accept: application/vnd.api+json;version=1

API 文档工具

工具	特性
OpenAPI (Swagger)	行业标准，自动生成文档
Postman	测试 + 文档
Insomnia	轻量级 API 客户端

---

API 设计检查清单

• 符合 RESTful 原则
  • 基于资源的 URL（名词、复数）
  • 使用恰当的 HTTP 方法
  • 使用正确的状态码
• 统一的错误响应格式
• 已定义身份验证/授权方式
• 已定义分页方式
• 版本控制方式（可选）

模板

• templates/pipeline/phase-4-api.template.md
• templates/pipeline/zero-script-qa.template.md

下一阶段

阶段 5：设计系统 → API 已就绪，现在开始构建 UI 组件