REST 与 GraphQL API 设计

引言

资源建模、状态码语义、版本策略与查询语言，对比 REST 与 GraphQL 的架构取舍与数据层设计。

本文作为「互联网基础架构」系列的第 09 篇，围绕「REST」这一主题展开。互联网的每一个基础组件都不是孤立的：它以特定的协议接入、以分层的方式处理、以冗余的方式容错。为了把「REST」背后的机制讲透，本文将使用 18 种不同的 Mermaid 图表类型、共 36 张图来呈现同一主题的不同侧面——从宏观的数据流到微观的报文结构，从状态机到部署拓扑，力求让读者形成立体认知。

阅读提示：每张图都对应一个独立的 Mermaid 语法类型，图与图之间相互补充。建议先通读文字，再逐一对照图表理解。

一、REST 的整体定位

在互联网架构中，REST 承担着承上启下的职责。理解它的定位，需要同时看清它的输入、核心处理与输出三个环节。

二、流程图（全部语法-1）

1.1 流程总览（流程图）

REST的完整流程可以抽象为「输入 → 核心处理 → 输出」三段。下面的流程图展示了REST在主链路上的关键环节：入口校验、核心处理、状态存储、结果分发，以及失败时的错误记录。图中的菱形节点代表判断分支，圆柱节点代表状态存储，圆角节点代表出入口——这正是 Mermaid 流程图在表示网络组件时的典型用法。

flowchart TB
  classDef z1 fill:#e3f2fd,stroke:#1976d2,color:#0d47a1
  classDef z2 fill:#f3e5f5,stroke:#8e24aa,color:#4a148c
  classDef z3 fill:#e0f7fa,stroke:#00838f,color:#004d40
  classDef z4 fill:#e8f5e9,stroke:#388e3c,color:#1b5e20
  subgraph IN[输入层 入口]
    direction LR
    A((用户REST接入)) --> B[REST接入参数解析]
    B --> C{REST是否合法}
  end
  subgraph CORE[核心层 处理]
    direction LR
    D[GraphQL处理逻辑] --> E[资源转发路由]
    E --> F[(状态GraphQL)]
  end
  subgraph OUT[输出层 响应]
    direction LR
    G[结果资源] --> H{GraphQL是否成功}
    H -->|成功| I[返回REST结果]
    H -->|失败| J[记录GraphQL错误]
  end
  C -->|通过| D
  C -->|拒绝| J
  F --> G
  I --> K((结束资源))
  E -.->|异步| F
  D ==> G
  class A z1
  class D z2
  class F z3
  class I z4
  click A "https://example.com/in" "REST入口"
  click F "https://example.com/state" "GraphQL状态"
  class IN z1
  class CORE z2
  class OUT z3

1.2 变体视角

下面的第二张流程图从另一个视角切入，与上图互为补充，共同构成对「REST」流程图的完整表达。

flowchart TB
  classDef z1 fill:#e3f2fd,stroke:#1976d2,color:#0d47a1
  classDef z2 fill:#f3e5f5,stroke:#8e24aa,color:#4a148c
  classDef z3 fill:#e0f7fa,stroke:#00838f,color:#004d40
  classDef z4 fill:#e8f5e9,stroke:#388e3c,color:#1b5e20
  subgraph IN[输入层 网关]
    direction LR
    A((用户REST请求)) --> B[REST请求参数解析]
    B --> C{REST是否合法}
  end
  subgraph CORE[核心层 调度]
    direction LR
    D[GraphQL校验逻辑] --> E[资源调度路由]
    E --> F[(状态GraphQL)]
  end
  subgraph OUT[输出层 返回]
    direction LR
    G[结果资源] --> H{GraphQL是否成功}
    H -->|成功| I[返回REST结果]
    H -->|失败| J[记录GraphQL错误]
  end
  C -->|通过| D
  C -->|拒绝| J
  F --> G
  I --> K((结束资源))
  E -.->|异步| F
  D ==> G
  class A z1
  class D z2
  class F z3
  class I z4
  click A "https://example.com/in" "REST入口"
  click F "https://example.com/state" "GraphQL状态"
  class IN z1
  class CORE z2
  class OUT z3

二、时序图（类型-2）

2.1 调用时序（时序图）

组件之间的协作顺序是理解REST的钥匙。下面的时序图展示了REST链路中用户端、网关、核心服务与存储之间的完整交互：同步调用的激活与返回、成功与失败分支、重试循环、审计记录与并行处理，以及超时中断的场景。

sequenceDiagram
  autonumber
  participant U as 用户端
  participant G as REST网关
  participant S as GraphQL服务
  participant D as 资源存储
  U->>G: 发起REST请求
  activate G
  G->>S: GraphQL调用
  activate S
  S->>D: 资源读写
  activate D
  D-->>S: 资源返回
  deactivate D
  alt GraphQL成功
    S-->>G: 成功响应
  else GraphQL失败
    S-->>G: 失败码
  end
  deactivate S
  G-->>U: REST最终响应
  deactivate G
  Note over G,S: 同步调用链路
  loop GraphQL重试
    G->>S: 重试请求
  end
  opt 审计
    S->>D: 记录REST日志
  end
  par 并行资源
    S->>S: 资源校验
    S->>S: 资源组装
  end
  break 超时
    G-->>U: 超时提示
  end

2.2 变体视角

下面的第二张时序图从另一个视角切入，与上图互为补充，共同构成对「REST」时序图的完整表达。

sequenceDiagram
  autonumber
  participant U as 用户端
  participant G as REST网关
  participant S as GraphQL服务
  participant D as 资源存储
  U->>G: 发送REST请求
  activate G
  G->>S: GraphQL调用
  activate S
  S->>D: 资源读写
  activate D
  D-->>S: 资源返回
  deactivate D
  alt GraphQL成功
    S-->>G: 成功响应
  else GraphQL失败
    S-->>G: 失败码
  end
  deactivate S
  G-->>U: REST最终响应
  deactivate G
  Note over G,S: 异步调用链路
  loop GraphQL重试
    G->>S: 重试请求
  end
  opt 审计
    S->>D: 记录REST日志
  end
  par 并行资源
    S->>S: 资源校验
    S->>S: 资源组装
  end
  break 超时
    G-->>U: 超时提示
  end

二、状态图（类型-3）

3.1 状态流转（状态图）

REST在生命周期内会经历多个状态。下面的状态图描绘了从初始化、就绪、运行到校验、完成的完整状态机，其中包含子状态（复合状态）、条件分支与失败重试回路，注释节点标注了校验条件与成功条件。

stateDiagram-v2
  direction LR
  [*] --> 初始化: REST开始
  初始化 --> 就绪
  就绪 --> 运行: 触发GraphQL
  state 运行 {
    子态A: GraphQL阶段一
    子态B: GraphQL阶段二
    子态A --> 子态B
  }
  运行 --> 校验: 资源完成
  校验 --> 完成: 通过
  校验 --> 重试: 失败
  重试 --> 运行: 再次GraphQL
  完成 --> [*]: 资源结束
  note right of 校验
    GraphQL条件判断
  end note
  note left of 完成
    REST成功资源
  end note

3.2 变体视角

下面的第二张状态图从另一个视角切入，与上图互为补充，共同构成对「REST」状态图的完整表达。

stateDiagram-v2
  direction LR
  [*] --> 初始化: REST开始
  初始化 --> 就绪
  就绪 --> 处理中: 触发GraphQL
  state 处理中 {
    子态A: GraphQL阶段一
    子态B: GraphQL阶段二
    子态A --> 子态B
  }
  处理中 --> 校验: 资源完成
  校验 --> 完成: 通过
  校验 --> 重试: 失败
  重试 --> 处理中: 再次GraphQL
  完成 --> [*]: 资源结束
  note right of 校验
    GraphQL条件判断
  end note
  note left of 完成
    REST成功资源
  end note

二、类图（类型-4）

4.1 组件职责（类图）

从面向对象视角看，REST由若干职责清晰的类协作完成。下面的类图定义了客户端、服务端与存储三类核心对象的属性与方法，并通过继承、组合、聚合、依赖与实现五种关系表达它们之间的耦合方式。

classDiagram
  class Client {
    +String RESTId
    +int retry
    +send() void
    +retry() void
  }
  class Service {
    +String GraphQLType
    -int status
    +process() Result
    +validate() bool
  }
  class Storage {
    +Map data
    +read() Object
    +write() bool
  }
  Client <|-- Service
  Client *-- Storage
  Service o-- Client
  Service ..> Storage
  Client ..|> Storage
  note for Service "REST核心逻辑"

4.2 变体视角

下面的第二张类图从另一个视角切入，与上图互为补充，共同构成对「REST」类图的完整表达。

classDiagram
  class Gateway {
    +String RESTId
    +int retry
    +send() void
    +retry() void
  }
  class Handler {
    +String GraphQLType
    -int status
    +process() Result
    +validate() bool
  }
  class Repo {
    +Map data
    +read() Object
    +write() bool
  }
  Gateway <|-- Handler
  Gateway *-- Repo
  Handler o-- Gateway
  Handler ..> Repo
  Gateway ..|> Repo
  note for Handler "REST核心逻辑"

二、实体关系图（类型-5）

5.1 数据模型（实体关系图）

REST背后的数据需要清晰的实体关系建模。下面的实体关系图定义了三个实体及其主外键，并用基数符号表达「一对多」「多对多」等关联约束，这是数据库表结构设计的直接依据。

erDiagram
  ENTITY_A ||--o{ ENTITY_B : REST
  ENTITY_B ||--|{ ENTITY_C : GraphQL
  ENTITY_A {
    string id PK
    string name
    string RESTKey FK
  }
  ENTITY_B {
    string id PK
    string GraphQLRef FK
    int count
  }
  ENTITY_C {
    string id PK
    string payload
  }

5.2 变体视角

下面的第二张实体关系图从另一个视角切入，与上图互为补充，共同构成对「REST」实体关系图的完整表达。

erDiagram
  ENTITY_A ||--o{ ENTITY_B : REST
  ENTITY_B ||--|{ ENTITY_C : GraphQL
  ENTITY_A {
    string id PK
    string name
    string RESTKey FK
  }
  ENTITY_B {
    string id PK
    string GraphQLRef FK
    int count
  }
  ENTITY_C {
    string id PK
    string payload
  }

二、甘特图（类型-6）

6.1 实施排期（甘特图）

工程落地需要排期。下面的甘特图展示了REST从准备、构建、验证到演练、发布的时间安排，任务之间的依赖关系用箭头表达，里程碑标记了关键节点。

gantt
  title REST实施计划
  dateFormat X
  axisFormat %L
  section GraphQL一期
    REST准备 :a1, 0, 2
    REST构建 :a2, after a1, 4
    REST验证 :a3, after a2, 2
  section 资源上线
    资源演练 :b1, after a3, 2
    资源发布 :milestone, b2, after b1, 0

6.2 变体视角

下面的第二张甘特图从另一个视角切入，与上图互为补充，共同构成对「REST」甘特图的完整表达。

gantt
  title REST演进计划
  dateFormat X
  axisFormat %L
  section GraphQL二期
    REST准备 :a1, 0, 2
    REST构建 :a2, after a1, 4
    REST验证 :a3, after a2, 2
  section 资源优化
    资源演练 :b1, after a3, 2
    资源发布 :milestone, b2, after b1, 0

二、饼图（类型-7）

7.1 构成分析（饼图）

REST的组成并非均质。下面的饼图用比例直观呈现了REST主流程与辅助分支的构成占比，帮助架构师判断优化投入的优先级。

pie showData
  title REST构成分析
  "REST 主流程" : 45
  "GraphQL 分支" : 30

7.2 变体视角

下面的第二张饼图从另一个视角切入，与上图互为补充，共同构成对「REST」饼图的完整表达。

pie showData
  title REST分布分析
  "REST 主流程" : 40
  "GraphQL 分支" : 25

二、旅程图（类型-8）

8.1 用户体验（旅程图）

从用户视角看，REST的体验分为多个阶段。下面的旅程图按阶段标注了REST各环节的用户满意度评分，得分越低越需要优化——它是体验导向架构分析的经典工具。

journey
  title REST核心旅程
  section GraphQL阶段
    REST发起: 5: 用户
    REST处理: 4: 系统
  section 资源阶段
    REST验证: 3: 用户
    REST交付: 5: 系统

8.2 变体视角

下面的第二张旅程图从另一个视角切入，与上图互为补充，共同构成对「REST」旅程图的完整表达。

journey
  title REST完整旅程
  section GraphQL阶段
    REST发起: 5: 用户
    REST处理: 4: 系统
  section 资源阶段
    REST验证: 3: 用户
    REST交付: 5: 系统

二、时间线图（类型-9）

9.1 演进历程（时间线图）

REST并非一蹴而就。下面的时间线图按时间顺序回顾了REST从雏形到标准化的演进脉络，帮助读者建立历史纵深感。

timeline
  title REST演进历程
  GraphQL初期 : REST雏形出现
  中期 : REST标准化
  资源期 : REST大规模应用
  未来 : REST持续演进

9.2 变体视角

下面的第二张时间线图从另一个视角切入，与上图互为补充，共同构成对「REST」时间线图的完整表达。

timeline
  title REST发展历程
  GraphQL初期 : REST雏形出现
  中期 : REST标准化
  资源期 : REST大规模应用
  未来 : REST持续演进

二、思维导图（类型-10）

10.1 知识地图（思维导图）

REST的知识体系庞大而分散。下面的思维导图以树状结构归纳了REST的输入要素、输出交付与主链路支撑，是复习与自查的便捷索引。

mindmap
  root((REST核心))
    GraphQL输入
      数据源
      配置项
    资源输出
      主结果
      附属结果
    REST主链路
      处理逻辑
      容错机制

10.2 变体视角

下面的第二张思维导图从另一个视角切入，与上图互为补充，共同构成对「REST」思维导图的完整表达。

mindmap
  root((REST总览))
    GraphQL前置
      数据源
      配置项
    资源交付
      主结果
      附属结果
    REST支撑
      处理逻辑
      容错机制

二、 Git 流程图（类型-11）

11.1 版本演进（Git 流程图）

工程协作中，REST的代码演进遵循分支管理规范。下面的Git 流程图模拟了特性分支开发、合入主分支、发布打标签与补丁摘取的完整流程。

gitGraph
  commit id: "base"
  branch feature
  checkout feature
  commit id: "REST-dev"
  commit id: "REST-int"
  checkout main
  merge feature
  commit id: "REST-rel" tag: "v1"
  cherry-pick id: "REST-dev"

11.2 变体视角

下面的第二张 Git 流程图从另一个视角切入，与上图互为补充，共同构成对「REST」Git 流程图的完整表达。

gitGraph
  commit id: "base"
  branch hotfix
  checkout hotfix
  commit id: "REST-dev"
  commit id: "REST-int"
  checkout main
  merge hotfix
  commit id: "REST-rel" tag: "v2"
  cherry-pick id: "REST-dev"

二、象限图（类型-12）

12.1 方案取舍（象限图）

REST的多种方案需要权衡。下面的象限图按「REST程度」与「GraphQL程度」两个维度划分四个象限，不同方案落入不同象限，直观支持选型决策。

quadrantChart
  title REST优先级象限
  x-axis 低 REST --> 高 REST
  y-axis 低 GraphQL --> 高 GraphQL
  quadrant-1 高GraphQL高REST
  quadrant-2 高GraphQL低REST
  quadrant-3 低GraphQL低REST
  quadrant-4 低GraphQL高REST
  REST方案A: [0.2, 0.8]
  REST方案B: [0.75, 0.65]

12.2 变体视角

下面的第二张象限图从另一个视角切入，与上图互为补充，共同构成对「REST」象限图的完整表达。

quadrantChart
  title REST价值象限
  x-axis 低 REST --> 高 REST
  y-axis 低 GraphQL --> 高 GraphQL
  quadrant-1 高GraphQL高REST
  quadrant-2 高GraphQL低REST
  quadrant-3 低GraphQL低REST
  quadrant-4 低GraphQL高REST
  REST方案C: [0.2, 0.8]
  REST方案D: [0.75, 0.65]

二、桑基图（类型-13）

13.1 流量流向（桑基图）

REST链路中的流量存在分流与合流。下面的桑基图用带宽度比例的连线展示REST从输入到处理再到输出的流量流向与损耗，是容量规划的重要参考。由于该图类型的语法限制，节点使用 ASCII 标识（如 dns-req、resolver-proc），语义与正文保持一致。

sankey-beta
  rest-req,gql-proc,120
  gql-proc,res-res,60

13.2 变体视角

下面的第二张桑基图从另一个视角切入，与上图互为补充，共同构成对「REST」桑基图的完整表达。

sankey-beta
  rest-in,gql-fwd,90
  gql-fwd,res-out,45

二、报文结构图（类型-14）

14.1 报文结构（报文结构图）

协议层面，REST的交互最终体现为固定格式的报文。下面的报文结构图按位域拆解了REST报文的类型、标识、长度与负载字段，是协议设计与抓包分析的基础。

packet-beta
  title REST请求报文
  0-7: "REST类型"
  8-15: "GraphQL标识"
  16-31: "资源长度"
  32-63: "数据负载"

14.2 变体视角

下面的第二张报文结构图从另一个视角切入，与上图互为补充，共同构成对「REST」报文结构图的完整表达。

packet-beta
  title REST响应报文
  0-7: "REST类型"
  8-15: "GraphQL标识"
  16-31: "资源长度"
  32-63: "数据负载"

二、块图（类型-15）

15.1 模块拓扑（块图）

系统层面，REST由入口、处理、存储与辅助模块构成。下面的块图以列布局和跨列块表达模块之间的依赖关系，辅助模块（监控、日志）以虚线关联。

block-beta
  columns 3
  A["REST入口"] B["GraphQL处理"] C["资源存储"]
  A-->B
  B-->C
  blockArrowId<["REST流程"]>(up)
  block D["REST辅助模块"]:2
    D1["监控"] D2["日志"]
  end
  C-->D
  B-.->D

15.2 变体视角

下面的第二张块图从另一个视角切入，与上图互为补充，共同构成对「REST」块图的完整表达。

block-beta
  columns 3
  A["REST入口"] B["GraphQL处理"] C["资源存储"]
  A-->B
  B-->C
  blockArrowId<["REST流程"]>(up)
  block D["REST辅助模块"]:2
    D1["监控"] D2["日志"]
  end
  C-->D
  B-.->D

二、 C4 上下文图（类型-16）

16.1 系统上下文（C4 上下文图）

从架构视图看，REST处在用户与依赖系统的中间。下面的C4 上下文图用 Person、System、SystemBoundary 三类元素勾勒出REST系统上下文，明确外部边界与内部核心模块。

C4Context
  title System Context
  Person(user, "User", "REST使用者")
  System(app, "RESTApp", "对外提供REST能力")
  System(dep, "资源Dep", "数据与GraphQL支撑")
  Rel(user, app, "use", "REST调用")
  Rel(app, dep, "dep", "GraphQL协同")
  System_Boundary(bound, "RESTBoundary") {
    System(inner, "GraphQLCore", "内部GraphQL模块")
  }
  Rel(app, inner, "contains", "GraphQL内部")

16.2 变体视角

下面的第二张 C4 上下文图从另一个视角切入，与上图互为补充，共同构成对「REST」C4 上下文图的完整表达。

C4Context
  title External Relation
  Person(user, "User", "REST使用者")
  System(app, "RESTApp", "对外提供REST能力")
  System(dep, "资源Dep", "数据与GraphQL支撑")
  Rel(user, app, "use", "REST调用")
  Rel(app, dep, "dep", "GraphQL协同")
  System_Boundary(bound, "RESTBoundary") {
    System(inner, "GraphQLCore", "内部GraphQL模块")
  }
  Rel(app, inner, "contains", "GraphQL内部")

二、 XY 折线图（类型-17）

17.1 性能曲线（XY 折线图）

量化评估需要曲线。下面的XY 折线图用折线呈现REST吞吐的上升趋势，用柱状图呈现延迟的变化，两者对照即可发现性能拐点。

xychart-beta
    title Throughput Trend
    x-axis [t1, t2, t3, t4, t5]
    y-axis "value" 0 --> 100
    line [20, 45, 60, 75, 90]
    bar [10, 25, 35, 50, 70]

17.2 变体视角

下面的第二张 XY 折线图从另一个视角切入，与上图互为补充，共同构成对「REST」XY 折线图的完整表达。

xychart-beta
    title Latency Trend
    x-axis [t1, t2, t3, t4, t5]
    y-axis "value" 0 --> 100
    line [20, 45, 60, 75, 90]
    bar [10, 25, 35, 50, 70]

二、架构图（类型-18）

18.1 部署拓扑（架构图）

最终，REST以集群形态落地。下面的架构图描绘了REST接入层与处理层的多实例部署、汇聚节点与存储的连线关系，以及实例间的对齐布局——这是生产架构图的核心形态。由于该图类型的语法限制，节点使用 ASCII 标识，语义与正文保持一致。

architecture-beta
    group g1(cloud)[rest_ClusterA]
    group g2(server)[gql_ClusterB]
    service s1(server)[rest_s1] in g1
    service s2(server)[rest_s2] in g1
    service m(mainframe)[res_store] in g2
    service j(junction)[gql_hub]
    s1:R --> L:j
    s2:R --> L:j
    j:B --> T:m
    align row s1 s2

18.2 变体视角

下面的第二张架构图从另一个视角切入，与上图互为补充，共同构成对「REST」架构图的完整表达。

architecture-beta
    group g1(cloud)[rest_Ingress]
    group g2(server)[gql_Process]
    service s1(server)[rest_s1] in g1
    service s2(server)[rest_s2] in g1
    service m(mainframe)[res_store] in g2
    service j(junction)[gql_hub]
    s1:R --> L:j
    s2:R --> L:j
    j:B --> T:m
    align row s1 s2

结语

至此，我们通过 18 种图类型、共 36 张图表，从流程、时序、状态、数据、排期、体验、演进、拓扑等多个维度完整审视了「REST」。希望读者能够体会到：REST不是单一组件，而是一张由协议、数据、状态与部署共同织成的网；掌握它，需要的是「多图对照、立体思考」的方法。

下一篇文章将继续深入互联网基础架构的另一个主题，敬请期待。