3. Service Catalog 接口概述

Service Catalog 作为云平台的服务目录中枢，对外暴露的接口是平台门户、CLI 工具、自动化流水线进行服务注册、发现、订阅与生命周期管理的核心通道。本章从接口类型、文档规范、版本策略和认证方式四个维度，系统梳理 Service Catalog 的接口体系。

3.1 接口类型：RESTful 与 gRPC 双协议

Service Catalog 同时支持 RESTful 和 gRPC 两种接口协议，分别面向不同的调用场景和客户端类型。

3.2 接口文档规范

Service Catalog 所有 RESTful 接口遵循 OpenAPI 3.0 规范编写文档，gRPC 接口通过 Proto 文件 定义。文档是接口调用的唯一权威参考，也是平台门户基线校验的比对基准。

3.2.1 RESTful 接口文档要求

• 路径设计：采用资源导向风格，如 /api/v1/catalog/services、/api/v1/catalog/plans。
• HTTP 方法：GET（查询）、POST（创建）、PUT（全量更新）、PATCH（部分更新）、DELETE（删除）。
• 请求/响应结构：统一封装 code、message、data 三层结构。
• 错误码：使用标准 HTTP 状态码 + 业务错误码组合。
• 示例：每个接口必须包含至少一个请求示例和一个响应示例。

openapi: 3.0.3
info:
  title: Service Catalog API
  version: 1.2.0
paths:
  /api/v1/catalog/services:
    get:
      summary: 获取服务列表
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: size
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: 成功返回服务列表
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 0
                  message:
                    type: string
                    example: "success"
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Service'

3.2.2 gRPC Proto 文件规范

• 包名：使用 catalog.v1 格式，与服务版本对齐。
• 服务定义：每个 RPC 方法必须包含明确的请求和响应消息类型。
• 字段编号：从 1 开始连续编号，预留扩展区间（1000+）。
• 注释：每个字段和服务方法必须附带中文或英文注释。

syntax = "proto3";
package catalog.v1;

service CatalogService {
  // 获取服务详情
  rpc GetService (GetServiceRequest) returns (GetServiceResponse);
  // 订阅服务
  rpc SubscribeService (SubscribeRequest) returns (SubscribeResponse);
}

message GetServiceRequest {
  string service_id = 1;   // 服务唯一标识
  string version = 2;      // 服务版本号
}

message GetServiceResponse {
  int32 code = 1;          // 状态码
  string message = 2;      // 状态描述
  Service data = 3;        // 服务详情
}

3.3 接口版本策略

Service Catalog 采用 语义化版本 + URL 路径版本 的双重版本管理策略，确保向后兼容和平滑升级。

3.4 接口认证方式

Service Catalog 接口采用 多因子认证 体系，根据调用方类型和敏感度级别选择不同的认证组合。

3.4.1 认证方式对比

3.4.2 认证流程要点

• 获取：调用 /api/v1/auth/ 接口，传入用户名/密码或 Client 凭证，返回 JWT 。
• 传递：所有 API 请求在 HTTP Header 中携带 Authorization: Bearer <>。
• 有效期：Access 默认 30 分钟，Refresh 默认 7 天。
• 传递：通过 Header X- 传递，适用于服务间低敏感度调用。
• 基线校验要求：平台门户基线校验时，必须验证认证失败场景的 HTTP 状态码是否为 401（未认证）或 403（无权限）。

3.4.3 认证失败响应示例

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "code": 401001,
  "message": " expired or invalid",
  "data": null
}

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "code": 403001,
  "message": "Insufficient permissions: requires 'catalog:admin' scope",
  "data": null
}