3. 主流契约规范对比

在契约驱动开发中，选择正确的契约规范直接影响团队协作效率、系统性能与可维护性。当前主流规范各有所长，分别对应不同的通信模式、数据序列化方式与生态偏好。本章从元模型、传输协议、消息模式、类型系统、版本治理与工具链六个维度进行横向对比，帮助团队在架构选型时做出理性决策。

3.1 四类规范的核心定位

3.2 元模型与契约结构对比

四种规范在契约的顶层结构、路径定义、消息描述与扩展机制上存在显著差异。以下通过一个“创建订单”的简化示例展示各自写法。

OpenAPI 3.x 片段

openapi: 3.0.3
info:
  title: 订单服务
  version: 1.0.0
paths:
  /orders:
    post:
      operationId: createOrder
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '201':
          description: 订单创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
components:
  schemas:
    CreateOrderRequest:
      type: object
      properties:
        userId:
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
    Order:
      type: object
      properties:
        orderId:
          type: string
        status:
          type: string

gRPC Protobuf 片段

syntax = "proto3";
package order.v1;

service OrderService {
  rpc CreateOrder(CreateOrderRequest) returns (Order);
}

message CreateOrderRequest {
  string user_id = 1;
  repeated OrderItem items = 2;
}

message Order {
  string order_id = 1;
  string status = 2;
}

message OrderItem {
  string product_id = 1;
  int32 quantity = 2;
}

AsyncAPI 片段

asyncapi: 2.6.0
info:
  title: 订单事件服务
  version: 1.0.0
channels:
  order/created:
    publish:
      message:
        $ref: '#/components/messages/OrderCreated'
components:
  messages:
    OrderCreated:
      payload:
        type: object
        properties:
          orderId:
            type: string
          userId:
            type: string
          totalAmount:
            type: number

GraphQL Schema 片段

type Query {
  order(id: ID!): Order
  ordersByUser(userId: ID!): [Order]
}

type Mutation {
  createOrder(input: CreateOrderInput!): Order
}

input CreateOrderInput {
  userId: ID!
  items: [OrderItemInput!]!
}

type Order {
  orderId: ID!
  status: OrderStatus!
  items: [OrderItem!]!
}

enum OrderStatus {
  PENDING
  CONFIRMED
  SHIPPED
}

3.3 关键维度对比矩阵

3.4 选择策略：场景驱动的决策树

3.5 混合使用策略

实际项目中，一个系统往往同时包含多种通信模式。以下推荐三种常见的混合架构模式：

• 分层混合：外部网关使用 OpenAPI 3.x 暴露 RESTful 接口，内部微服务间使用 gRPC Protobuf 通信，事件通知使用 AsyncAPI 定义。
• BFF 模式：前端通过 GraphQL Schema 聚合多个后端服务的数据，后端服务之间使用 gRPC 或 OpenAPI 同步调用，异步事件使用 AsyncAPI 治理。
• 事件驱动 + 查询分离：命令侧使用 gRPC 或 OpenAPI 处理写请求，查询侧使用 GraphQL 提供灵活读取，事件流使用 AsyncAPI 解耦。

3.6 选择检查清单