4. 定义 Topic 管理 API：创建、删除与查询

Topic（主题）是消息队列中最核心的命名空间实体，所有消息的发布与订阅都围绕 Topic 进行。本章将基于 OpenAPI 3.0 规范，为 Topic 管理定义三个标准 RESTful 端点：POST /topics（创建）、DELETE /topics/{topicId}（删除）和 GET /topics（查询列表）。我们不仅关注接口的请求/响应结构，更强调错误链路的完整设计，确保客户端能够根据明确的错误码进行精准的异常处理。

4.1 接口概览与契约清单

下表列出了三个核心 Topic 管理接口的 HTTP 方法、路径、主要用途以及预期的成功状态码。所有接口均采用 JSON 作为请求与响应的序列化格式。

4.2 创建 Topic：POST /topics

创建 Topic 是管理入口的第一步。客户端需要提供 Topic 名称、描述以及可选的配置参数。服务端在成功创建后，必须返回完整的 Topic 对象，包括系统生成的唯一 ID 和创建时间戳。

4.2.1 请求体结构

{
  "topicName": "order.created",
  "description": "订单创建事件主题",
  "messageRetentionInHours": 72,
  "maxMessageSize": 1048576
}

4.2.2 成功响应（201 Created）

{
  "topicId": "tp-20250321-abc123",
  "topicName": "order.created",
  "description": "订单创建事件主题",
  "messageRetentionInHours": 72,
  "maxMessageSize": 1048576,
  "createdAt": "2025-03-21T10:30:00Z",
  "status": "ACTIVE"
}

4.2.3 错误响应链路

创建接口可能返回以下错误，客户端应根据 errorCode 进行差异化处理：

4.3 删除 Topic：DELETE /topics/{topicId}

删除操作需要指定 Topic 的唯一 ID。由于删除是不可逆操作，服务端必须进行严格的权限校验和资源状态检查。成功删除后返回 204，不包含响应体。

4.3.1 路径参数

4.3.2 错误响应链路

删除接口的错误处理需要覆盖资源不存在、资源被占用以及内部状态异常等场景：

4.4 查询 Topic 列表：GET /topics

列表查询接口支持分页和可选的名称模糊搜索。响应体采用标准的分页封装，包含当前页数据、总记录数以及分页元信息。

4.4.1 查询参数

4.4.2 成功响应（200 OK）

{
  "topics": [
    {
      "topicId": "tp-20250321-abc123",
      "topicName": "order.created",
      "description": "订单创建事件主题",
      "status": "ACTIVE",
      "createdAt": "2025-03-21T10:30:00Z"
    },
    {
      "topicId": "tp-20250321-def456",
      "topicName": "payment.success",
      "description": "支付成功事件主题",
      "status": "ACTIVE",
      "createdAt": "2025-03-21T11:00:00Z"
    }
  ],
  "nextPageToken": "eyJsYXN0SWQiOiJ0cC0yMDI1MDMyMS1kZWY0NTYifQ==",
  "totalCount": 42
}

4.4.3 错误响应链路

4.5 错误处理链路全景图

下面的 SVG 图展示了三个 Topic 管理接口的完整错误处理链路，包括客户端发起请求、服务端校验、业务逻辑处理以及错误响应的标准化流程。

4.6 标准化错误响应体设计

所有错误响应必须遵循统一的 JSON 结构，确保客户端可以基于 errorCode 字段进行编程式处理，而不是解析文本消息。

{
  "error": {
    "code": "TOPIC_ALREADY_EXISTS",
    "message": "Topic 'order.created' already exists.",
    "details": {
      "existingTopicId": "tp-20250321-abc123",
      "conflictField": "topicName"
    },
    "requestId": "req-7a1b2c3d-4e5f-6789-abcd-ef0123456789",
    "timestamp": "2025-03-21T10:30:05Z"
  }
}

4.7 本章小结

Topic 管理 API 的设计核心在于三点：

• 资源语义清晰： 创建返回 201 + 完整资源，删除返回 204 无响应体，查询返回 200 + 分页结构。
• 错误码精细化： 每个错误场景都有唯一的 errorCode，客户端可以根据 code 而非 message 做决策。
• 错误体标准化： 统一的 JSON 结构包含 code、message、details、requestId 和 timestamp，便于日志追踪和自动化处理。