Codar 预置工作流

API 设计

设计 RESTful API 或 RPC 接口,定义资源、路由、请求响应格式和错误处理

通用6 个步骤v1更新于 2026-11-20

流程图

  • 数据输入
  • 预处理
  • 核心分析
  • 结果输出

步骤说明6 步

  1. 明确业务需求数据输入

    理解核心业务场景、数据模型和用户角色,确认功能边界。

    下一步02 设计资源和路由

  2. 设计资源和路由预处理

    定义资源层次、HTTP 方法和 URL 结构,遵循 RESTful 原则或 RPC 约定。考虑版本管理策略。

    下一步03 定义请求响应格式

  3. 定义请求响应格式核心分析

    设计 JSON Schema,明确必填字段、类型约束和默认值。统一响应格式(成功、错误、分页)。

    下一步04 错误处理和状态码05 鉴权和限流策略

  4. 错误处理和状态码核心分析

    定义错误码体系和 HTTP 状态码映射,提供清晰的错误信息。考虑国际化。

    下一步06 编写 API 文档

  5. 鉴权和限流策略核心分析

    设计认证方式(Token/OAuth)、权限模型和 Rate Limiting 策略。

    下一步06 编写 API 文档

  6. 编写 API 文档结果输出

    使用 OpenAPI/Swagger 描述接口,给出示例请求和响应,说明边界情况。

使用原则

  • 参考上述步骤、工具和依赖关系,结合本次目标、数据与可用工具安排研究过程。
  • 可以调整顺序、补充必要检查或省略不适用的步骤,重要调整需说明原因。
  • 用户本次的明确要求优先于此参考;关键意图不清楚时先提问。

workflow.md

查看工作流源文件
---
format: codar-workflow
schemaVersion: 1
layoutDirection: TD
id: "api-design-4jolpawq"
version: 1
name: "API 设计"
domain: "通用"
description: "设计 RESTful API 或 RPC 接口,定义资源、路由、请求响应格式和错误处理"
---

# API 设计

## 流程图

```mermaid
flowchart TD
    n1["明确业务需求"]
    n2["设计资源和路由"]
    n3["定义请求响应格式"]
    n4["错误处理和状态码"]
    n5["鉴权和限流策略"]
    n6["编写 API 文档"]
    n1 --> n2
    n2 --> n3
    n3 --> n4
    n3 --> n5
    n4 --> n6
    n5 --> n6
```

## 节点

### 明确业务需求 {#n1}
- 类别: 数据输入
- 位置: 165, 40
- 说明: |
  理解核心业务场景、数据模型和用户角色,确认功能边界。

### 设计资源和路由 {#n2}
- 类别: 预处理
- 位置: 165, 176
- 说明: |
  定义资源层次、HTTP 方法和 URL 结构,遵循 RESTful 原则或 RPC 约定。考虑版本管理策略。

### 定义请求响应格式 {#n3}
- 类别: 核心分析
- 位置: 165, 312
- 说明: |
  设计 JSON Schema,明确必填字段、类型约束和默认值。统一响应格式(成功、错误、分页)。

### 错误处理和状态码 {#n4}
- 类别: 核心分析
- 位置: 40, 448
- 说明: |
  定义错误码体系和 HTTP 状态码映射,提供清晰的错误信息。考虑国际化。

### 鉴权和限流策略 {#n5}
- 类别: 核心分析
- 位置: 290, 448
- 说明: |
  设计认证方式(Token/OAuth)、权限模型和 Rate Limiting 策略。

### 编写 API 文档 {#n6}
- 类别: 结果输出
- 位置: 165, 584
- 说明: |
  使用 OpenAPI/Swagger 描述接口,给出示例请求和响应,说明边界情况。

## 使用原则

- 参考上述步骤、工具和依赖关系,结合本次目标、数据与可用工具安排研究过程。
- 可以调整顺序、补充必要检查或省略不适用的步骤,重要调整需说明原因。
- 用户本次的明确要求优先于此参考;关键意图不清楚时先提问。