SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场phase-4-api

phase-4-api

编程与开发

查看项目

更新于 10-16 02:20

技能介绍

用途

phase-4-api 是 bkit-claude-code 流水线中的第四阶段，目标是实现能够存储和检索数据的后端 API，并通过结构化日志而非测试脚本来验证其行为。触发场景包括 API 设计、REST API、后端、端点（endpoint）等。

主要能力

本阶段包含三项核心工作：

  1. API 设计：定义端点、请求与响应。
  2. API 实现：编写实际的后端代码。
  3. Zero Script 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 应用

  • Plan：定义所需 API 列表
  • Design：设计端点、请求与响应
  • Do：实现 API
  • Check：用 Zero Script QA 验证
  • Act：修复缺陷并进入第五阶段

按级别应用

级别 应用方式
Starter 跳过此阶段（无 API）
Dynamic 使用 bkend.ai BaaS（见下文）
Enterprise 直接实现 API

Dynamic 级别：bkend.ai BaaS API 实现

步骤 1：MCP 设置

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

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

自然语言请求：“Create a users table with name(required), email(required, unique), age fields” -> 自动调用 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：Zero Script QA

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

什么是 Zero Script QA？

不编写测试脚本，而是用结构化调试日志进行验证：

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

优势：

  • 节省编写测试代码的时间
  • 用肉眼观察实际行为
  • 便于调试

RESTful API 原则

什么是 REST？

REpresentational State Transfer——一种用于设计 Web 服务的架构风格。

六项核心原则

原则 说明 示例
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": "user@example.com",
    "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. 使用小写 ✅ /users/123/orders ❌ /Users/123/Orders

  2. 使用连字符（-），避免下划线（_） ✅ /user-profiles ❌ /user_profiles

  3. 表达层级关系 ✅ /users/123/orders/456

  4. 通过查询参数过滤 ✅ /users?status=active&sort=created_at ❌ /users/active/sort/created_at

  5. 版本管理 ✅ /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

下一阶段

Phase 5：设计系统 → API 已就绪，接下来构建 UI 组件。

限制

资料未提供该技能的具体收费、价格、平台支持范围或实际效果数据。