如何发布和引用服务

openapi: 3.1.0
info:
  title: 用户服务 API
  version: 1.2.0
  summary: 用户管理相关接口
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
 
servers:
  - url: https://api.example.com/v1
    description: 生产环境
  - url: https://staging-api.example.com/v1
    description: 预发布环境
 
# JSON Schema Draft 2020-12 对齐
jsonSchemaDialect: https://json-schema.org/draft/2020-12/schema
 
# 组件定义（使用 $defs 替代 definitions）
components:
  schemas:
    User:
      type: object
      required: [id, name]
      properties:
        id:
          type: integer
          format: int64
          description: 用户唯一标识
        name:
          type: string
          minLength: 1
          maxLength: 100
        email:
          type: string
          format: email
        status:
          $ref: '#/components/schemas/UserStatus'
      # 条件 Schema 示例
      if:
        properties:
          status:
            const: active
      then:
        required: [email]
 
    UserStatus:
      type: string
      enum: [active, inactive, suspended]
 
paths:
  /users:
    get:
      operationId: listUsers
      summary: 获取用户列表
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: 成功返回用户列表
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
 
    post:
      operationId: createUser
      summary: 创建用户
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '201':
          description: 用户创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
 
# Webhook 定义（3.1 新增）
webhooks:
  userCreated:
    post:
      summary: 用户创建事件通知
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserEvent'
      responses:
        '200':
          description: 事件处理成功
 
# 安全方案
security:
  - bearerAuth: []
  - oauth2: [read, write]
 
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/authorize
          tokenUrl: https://auth.example.com/token
          scopes:
            read: 读取权限
            write: 写入权限
    mutualTLS:
      type: mutualTLS
      description: 双向 TLS 认证

// 依赖配置（build.gradle）
dependencies {
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.5.0'
    implementation 'org.springframework.cloud:spring-cloud-starter-openfeign:4.1.0'
}
 
// Controller 注解
@RestController
@RequestMapping("/api/v1/users")
@Tag(name = "User API", description = "用户管理接口")
public class UserController {
 
    @Operation(summary = "获取用户列表", operationId = "listUsers")
    @ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "成功"),
        @ApiResponse(responseCode = "401", description = "未授权")
    })
    @GetMapping
    public ResponseEntity<PageResponse<User>> listUsers(
        @Parameter(description = "页码") @RequestParam(defaultValue = "1") Integer page,
        @Parameter(description = "每页数量") @RequestParam(defaultValue = "20") Integer pageSize
    ) {
        // 实现逻辑
    }
}
 
// OpenAPI 配置
@Configuration
public class OpenApiConfig {
 
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
            .info(new Info()
                .title("用户服务 API")
                .version("1.2.0")
                .description("用户管理相关接口"))
            .addSecurityItem(new SecurityRequirement().addList("bearerAuth"))
            .components(new Components()
                .addSecuritySchemes("bearerAuth",
                    new SecurityScheme()
                        .type(SecurityScheme.Type.HTTP)
                        .scheme("bearer")
                        .bearerFormat("JWT")));
    }
}

// user_service.proto
syntax = "proto3";
 
package com.example.user.v1;
 
option go_package = "github.com/example/proto/user/v1;userv1";
option java_multiple_files = true;
option java_package = "com.example.user.v1";
option java_outer_classname = "UserServiceProto";
 
import "google/protobuf/timestamp.proto";
import "google/protobuf/field_mask.proto";
import "google/api/annotations.proto";  // Google API HTTP 映射
import "google/api/client.proto";
import "validate/validate.proto";       // protoc-gen-validate 验证规则
 
// 服务定义
service UserService {
  option (google.api.default_host) = "user-service.example.com";
 
  // 一元 RPC
  rpc GetUser(GetUserRequest) returns (User) {
    option (google.api.http) = {
      get: "/v1/users/{user_id}"
    };
  }
 
  // 服务端流式 RPC
  rpc ListUsers(ListUsersRequest) returns (stream User) {
    option (google.api.http) = {
      get: "/v1/users"
    };
  }
 
  // 客户端流式 RPC
  rpc CreateUsers(stream CreateUserRequest) returns (CreateUsersResponse) {
    option (google.api.http) = {
      post: "/v1/users:batchCreate"
    };
  }
 
  // 双向流式 RPC
  rpc StreamEvents(stream EventRequest) returns (stream EventResponse);
 
  // 带字段掩码的部分更新
  rpc UpdateUser(UpdateUserRequest) returns (User) {
    option (google.api.http) = {
      patch: "/v1/users/{user_id}"
      body: "user"
    };
  }
 
  // 删除用户
  rpc DeleteUser(DeleteUserRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/v1/users/{user_id}"
    };
  }
}
 
// 消息定义
message User {
  string user_id = 1 [(validate.rules).string.uuid = true];
  string name = 2 [(validate.rules).string = {min_len: 1, max_len: 100}];
  string email = 3 [(validate.rules).string.email = true];
  UserStatus status = 4;
  google.protobuf.Timestamp created_at = 5;
  google.protobuf.Timestamp updated_at = 6;
  map<string, string> metadata = 7;
}
 
message GetUserRequest {
  string user_id = 1 [(validate.rules).string.uuid = true];
}
 
message ListUsersRequest {
  int32 page_size = 1 [(validate.rules).int32 = {gte: 1, lte: 100}];
  string page_token = 2;
  string filter = 3;  // CEL 表达式过滤
}
 
message CreateUserRequest {
  string name = 1 [(validate.rules).string = {min_len: 1, max_len: 100}];
  string email = 2 [(validate.rules).string.email = true];
}
 
message UpdateUserRequest {
  string user_id = 1 [(validate.rules).string.uuid = true];
  User user = 2;
  google.protobuf.FieldMask update_mask = 3;  // 部分更新字段掩码
}
 
message DeleteUserRequest {
  string user_id = 1 [(validate.rules).string.uuid = true];
  bool force = 2;  // 强制删除
}
 
message CreateUsersResponse {
  repeated string user_ids = 1;
  int32 success_count = 2;
  int32 failure_count = 3;
}
 
enum UserStatus {
  USER_STATUS_UNSPECIFIED = 0;
  USER_STATUS_ACTIVE = 1;
  USER_STATUS_INACTIVE = 2;
  USER_STATUS_SUSPENDED = 3;
}

# gRPC 引导配置 (bootstrap.json)
{
  "xds_servers": [
    {
      "server_uri": "istiod.istio-system.svc:15012",
      "channel_creds": [
        {
          "type": "insecure"
        }
      ],
      "server_features": ["xds_v3"]
    }
  ],
  "node": {
    "id": "sidecar~10.244.0.1~user-service-abc123.default~default.svc.cluster.local",
    "metadata": {
      "NAMESPACE": "default",
      "SERVICE_NAME": "user-service"
    }
  },
  "certificate_providers": {
    "default": {
      "plugin_name": "file_watcher",
      "config": {
        "certificate_file": "/etc/certs/cert-chain.pem",
        "private_key_file": "/etc/certs/key.pem",
        "ca_certificate_file": "/etc/certs/root-cert.pem"
      }
    }
  }
}

// 服务端实现
public class UserServiceImpl extends UserServiceGrpc.UserServiceImplBase {
 
    private final UserRepository userRepository;
    private final Meter meter;  // OpenTelemetry Metrics
 
    @Override
    public void getUser(GetUserRequest request,
                        StreamObserver<User> responseObserver) {
        // OpenTelemetry Span
        Span span = Span.current();
        span.setAttribute("user.id", request.getUserId());
 
        User user = userRepository.findById(request.getUserId())
            .orElseThrow(() -> Status.NOT_FOUND
                .withDescription("User not found: " + request.getUserId())
                .asRuntimeException());
 
        responseObserver.onNext(user);
        responseObserver.onCompleted();
    }
 
    @Override
    public void listUsers(ListUsersRequest request,
                          StreamObserver<User> responseObserver) {
        // 服务端流式响应
        userRepository.findAll(PageRequest.of(
            request.getPageSize(),
            0,
            Sort.by("createdAt").descending()
        )).forEach(user -> {
            responseObserver.onNext(user);
        });
        responseObserver.onCompleted();
    }
 
    @Override
    public StreamObserver<CreateUserRequest> createUsers(
            StreamObserver<CreateUsersResponse> responseObserver) {
        // 客户端流式处理
        return new StreamObserver<>() {
            private final List<String> createdIds = new ArrayList<>();
            private int failureCount = 0;
 
            @Override
            public void onNext(CreateUserRequest request) {
                try {
                    User user = userRepository.save(
                        User.newBuilder()
                            .setName(request.getName())
                            .setEmail(request.getEmail())
                            .setStatus(UserStatus.USER_STATUS_ACTIVE)
                            .build()
                    );
                    createdIds.add(user.getUserId());
                } catch (Exception e) {
                    failureCount++;
                }
            }
 
            @Override
            public void onError(Throwable t) {
                responseObserver.onError(t);
            }
 
            @Override
            public void onCompleted() {
                responseObserver.onNext(CreateUsersResponse.newBuilder()
                    .addAllUserIds(createdIds)
                    .setSuccessCount(createdIds.size())
                    .setFailureCount(failureCount)
                    .build());
                responseObserver.onCompleted();
            }
        };
    }
}
 
// 服务端启动配置
public class GrpcServer {
 
    public static void main(String[] args) throws Exception {
        Server server = ServerBuilder.forPort(9090)
            // OpenTelemetry 拦截器
            .intercept(new GrpcTelemetryServerInterceptor())
            // 健康检查服务
            .addService(new HealthGrpc.HealthImplBase() {
                @Override
                public void check(HealthCheckRequest request,
                                  StreamObserver<HealthCheckResponse> responseObserver) {
                    responseObserver.onNext(HealthCheckResponse.newBuilder()
                        .setStatus(ServingStatus.SERVING)
                        .build());
                    responseObserver.onCompleted();
                }
            })
            // 反射服务（用于 grpcurl 调试）
            .addService(ProtoReflectionService.newInstance())
            // 业务服务
            .addService(new UserServiceImpl())
            // xDS 支持
            .addService(XdsServerBuilder.create())
            .build()
            .start();
 
        server.awaitTermination();
    }
}
 
// 客户端调用
public class UserServiceClient {
 
    private final UserServiceGrpc.UserServiceBlockingStub blockingStub;
    private final UserServiceGrpc.UserServiceStub asyncStub;
 
    public UserServiceClient(String target) {
        // xDS 目标格式: xds:///user-service.default.svc.cluster.local
        ManagedChannel channel = ManagedChannelBuilder.forTarget(target)
            .defaultLoadBalancingPolicy("round_robin")
            .enableRetry()  // 启用重试
            .maxRetryAttempts(3)
            .build();
 
        this.blockingStub = UserServiceGrpc.newBlockingStub(channel);
        this.asyncStub = UserServiceGrpc.newStub(channel);
    }
 
    public User getUser(String userId) {
        return blockingStub.getUser(
            GetUserRequest.newBuilder()
                .setUserId(userId)
                .build()
        );
    }
 
    // 异步流式调用
    public void listUsers(int pageSize, Consumer<User> consumer) {
        asyncStub.listUsers(
            ListUsersRequest.newBuilder()
                .setPageSize(pageSize)
                .build(),
            new StreamObserver<>() {
                @Override
                public void onNext(User user) {
                    consumer.accept(user);
                }
 
                @Override
                public void onError(Throwable t) {
                    // 错误处理
                }
 
                @Override
                public void onCompleted() {
                    // 完成回调
                }
            }
        );
    }
}

# user.graphqls - 用户服务 Schema
extend schema
  @link(url: "https://specs.apollo.dev/federation/v2.5",
        import: ["@key", "@requires", "@provides", "@external", "@shareable"])
 
type User @key(fields: "id") {
  id: ID!
  name: String!
  email: String!
  status: UserStatus!
  createdAt: DateTime!
  updatedAt: DateTime!
 
  # 关联数据（来自其他服务）
  orders: [Order!]! @requires(fields: "id")
  profile: UserProfile
}
 
type UserProfile @shareable {
  avatar: String
  bio: String
  preferences: UserPreferences
}
 
type UserPreferences {
  language: String
  theme: Theme
  notifications: NotificationSettings
}
 
enum UserStatus {
  ACTIVE
  INACTIVE
  SUSPENDED
}
 
enum Theme {
  LIGHT
  DARK
  SYSTEM
}
 
type NotificationSettings {
  email: Boolean!
  push: Boolean!
  sms: Boolean!
}
 
input UserFilter {
  status: UserStatus
  search: String
  createdAfter: DateTime
}
 
input CreateUserInput {
  name: String!
  email: String!
}
 
input UpdateUserInput {
  name: String
  email: String
  status: UserStatus
}
 
type Query {
  user(id: ID!): User
  users(filter: UserFilter, page: Int, pageSize: Int): UserConnection!
  me: User!  # 当前登录用户
}
 
type Mutation {
  createUser(input: CreateUserInput!): User!
  updateUser(id: ID!, input: UpdateUserInput!): User!
  deleteUser(id: ID!): Boolean!
}
 
type UserConnection {
  edges: [UserEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}
 
type UserEdge {
  node: User!
  cursor: String!
}
 
type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}
 
scalar DateTime @shareable

// 用户服务 Resolver
import { ApolloServer } from '@apollo/server';
import { buildSubgraphSchema } from '@apollo/subgraph';
import { startStandaloneServer } from '@apollo/server/standalone';
import gql from 'graphql-tag';
 
const typeDefs = gql`
  extend schema
    @link(url: "https://specs.apollo.dev/federation/v2.5",
          import: ["@key", "@requires", "@external"])
 
  type User @key(fields: "id") {
    id: ID!
    name: String!
    email: String!
    status: UserStatus!
    createdAt: DateTime!
    orders: [Order!]! @requires(fields: "id")
  }
 
  enum UserStatus {
    ACTIVE
    INACTIVE
    SUSPENDED
  }
 
  type Query {
    user(id: ID!): User
    users(filter: UserFilter, page: Int, pageSize: Int): UserConnection!
  }
`;
 
const resolvers = {
  Query: {
    user: async (_, { id }, { dataSources }) => {
      return dataSources.userAPI.getUser(id);
    },
    users: async (_, { filter, page = 1, pageSize = 20 }, { dataSources }) => {
      return dataSources.userAPI.getUsers(filter, page, pageSize);
    }
  },
  User: {
    // Federation 实体解析器
    __resolveReference: async (user, { dataSources }) => {
      return dataSources.userAPI.getUser(user.id);
    },
    orders: async (user, _, { dataSources }) => {
      // 调用订单服务获取用户订单
      return dataSources.orderAPI.getOrdersByUserId(user.id);
    }
  }
};
 
const server = new ApolloServer({
  schema: buildSubgraphSchema({ typeDefs, resolvers }),
  introspection: true
});
 
// 启动服务
const { url } = await startStandaloneServer(server, {
  listen: { port: 4001 },
  context: async ({ req }) => ({
    dataSources: {
      userAPI: new UserAPI(),
      orderAPI: new OrderAPI()
    }
  })
});
 
console.log(`🚀 User service ready at ${url}`);

# Apollo Router 配置 (router.yaml)
supergraph:
  listen: 0.0.0.0:4000
  introspection: true
 
subgraphs:
  user:
    routing_url: http://user-service:4001/graphql
  order:
    routing_url: http://order-service:4002/graphql
  product:
    routing_url: http://product-service:4003/graphql
 
# 认证配置
authentication:
  subgraphs:
    user:
      forward_headers:
        - Authorization
 
# 限流配置
limits:
  max_depth: 10
  max_height: 100
  max_aliases: 20
  max_root_fields: 20
 
# 缓存配置
traffic_shaping:
  all:
    deduplicate_query: true
    compression:
      enabled: true

asyncapi: 2.6.0
info:
  title: 用户事件服务
  version: 1.0.0
  description: 用户相关事件的发布与订阅契约
  contact:
    name: 平台架构组
    email: platform@example.com
 
servers:
  production:
    url: kafka-prod.example.com:9092
    protocol: kafka
    description: 生产环境 Kafka 集群
    bindings:
      kafka:
        schemaRegistryUrl: https://schema-registry.example.com
        schemaRegistryVendor: confluent
 
  staging:
    url: kafka-staging.example.com:9092
    protocol: kafka
    description: 预发布环境
 
defaultContentType: application/json
 
channels:
  user.created:
    description: 用户创建事件
    publish:
      summary: 发布用户创建事件
      operationId: publishUserCreated
      message:
        $ref: '#/components/messages/UserCreated'
      bindings:
        kafka:
          partitions: 6
          replicas: 3
          key:
            type: string
            description: 用户ID作为分区键
 
  user.updated:
    description: 用户更新事件
    publish:
      operationId: publishUserUpdated
      message:
        $ref: '#/components/messages/UserUpdated'
    subscribe:
      summary: 订阅用户更新事件
      operationId: subscribeUserUpdated
      message:
        $ref: '#/components/messages/UserUpdated'
 
  user.deleted:
    description: 用户删除事件
    publish:
      operationId: publishUserDeleted
      message:
        $ref: '#/components/messages/UserDeleted'
 
  user.events:
    description: 用户事件聚合流（Kafka Streams）
    subscribe:
      operationId: subscribeUserEvents
      message:
        oneOf:
          - $ref: '#/components/messages/UserCreated'
          - $ref: '#/components/messages/UserUpdated'
          - $ref: '#/components/messages/UserDeleted'
 
components:
  messages:
    UserCreated:
      name: UserCreated
      title: 用户创建事件
      contentType: application/json
      payload:
        $ref: '#/components/schemas/UserCreatedPayload'
      headers:
        $ref: '#/components/schemas/EventHeaders'
      bindings:
        kafka:
          key:
            $ref: '#/components/schemas/UserId'
          schemaIdLocation: payload
 
    UserUpdated:
      name: UserUpdated
      title: 用户更新事件
      contentType: application/json
      payload:
        $ref: '#/components/schemas/UserUpdatedPayload'
      headers:
        $ref: '#/components/schemas/EventHeaders'
      bindings:
        kafka:
          schemaIdLocation: header
          schemaIdPayloadEncoding: json
 
    UserDeleted:
      name: UserDeleted
      title: 用户删除事件
      contentType: application/json
      payload:
        $ref: '#/components/schemas/UserDeletedPayload'
 
  schemas:
    EventHeaders:
      type: object
      properties:
        eventId:
          type: string
          format: uuid
          description: 事件唯一标识
        eventType:
          type: string
          enum: [UserCreated, UserUpdated, UserDeleted]
        eventVersion:
          type: string
          default: "1.0"
        timestamp:
          type: string
          format: date-time
        source:
          type: string
          description: 事件来源服务
        correlationId:
          type: string
          format: uuid
          description: 关联ID（用于追踪）
 
    UserCreatedPayload:
      type: object
      required: [userId, name, email, timestamp]
      properties:
        userId:
          $ref: '#/components/schemas/UserId'
        name:
          type: string
          minLength: 1
          maxLength: 100
        email:
          type: string
          format: email
        status:
          type: string
          enum: [active, inactive]
          default: active
        timestamp:
          type: string
          format: date-time
        metadata:
          type: object
          additionalProperties: true
 
    UserUpdatedPayload:
      type: object
      required: [userId, timestamp]
      properties:
        userId:
          $ref: '#/components/schemas/UserId'
        changes:
          type: object
          description: 变更字段（JSON Patch 格式）
        oldValues:
          type: object
          description: 变更前的值
        timestamp:
          type: string
          format: date-time
 
    UserDeletedPayload:
      type: object
      required: [userId, timestamp]
      properties:
        userId:
          $ref: '#/components/schemas/UserId'
        reason:
          type: string
          description: 删除原因
        deletedBy:
          type: string
          description: 操作人
        timestamp:
          type: string
          format: date-time
 
    UserId:
      type: string
      format: uuid
      description: 用户唯一标识
 
# 安全配置
security:
  - kafkaScram: []
 
components:
  securitySchemes:
    kafkaScram:
      type: scramSha256
      description: Kafka SCRAM-SHA-256 认证

# AsyncAPI CLI 工具
# 安装
npm install -g @asyncapi/cli
 
# 验证文档
asyncapi validate asyncapi.yaml
 
# 生成文档
asyncapi generate docs asyncapi.yaml html -o ./docs
 
# 生成代码
asyncapi generate fromTemplate asyncapi.yaml @asyncapi/java-spring-template -o ./src
 
# 生成 Kafka 消费者/生产者代码
asyncapi generate fromTemplate asyncapi.yaml @asyncapi/java-spring-kafka-template \
  -p javaPackage=com.example.user.events \
  -o ./generated

// 接口定义（支持 Protobuf 注解）
public interface UserService {
 
    // 一元调用
    User getUser(GetUserRequest request);
 
    // 服务端流
    Iterator<User> listUsers(ListUsersRequest request);
 
    // 双向流
    StreamObserver<CreateUserRequest> createUsers(StreamObserver<CreateUsersResponse> responseObserver);
}
 
// Protobuf 消息定义
@Protobuf
public class User {
    @Protobuf(fieldType = FieldType.STRING, order = 1)
    private String userId;
 
    @Protobuf(fieldType = FieldType.STRING, order = 2)
    private String name;
 
    @Protobuf(fieldType = FieldType.STRING, order = 3)
    private String email;
 
    @Protobuf(fieldType = FieldType.ENUM, order = 4)
    private UserStatus status;
}
 
// 服务实现
@DubboService(
    protocol = "tri",  // Triple 协议
    version = "1.0.0",
    group = "user-service",
    timeout = 5000,
    retries = 2,
    loadbalance = "roundrobin"
)
public class UserServiceImpl implements UserService {
 
    @Override
    public User getUser(GetUserRequest request) {
        return userRepository.findById(request.getUserId())
            .orElseThrow(() -> new NotFoundException("User not found"));
    }
 
    @Override
    public Iterator<User> listUsers(ListUsersRequest request) {
        return userRepository.findAll().iterator();
    }
 
    @Override
    public StreamObserver<CreateUserRequest> createUsers(
            StreamObserver<CreateUsersResponse> responseObserver) {
        return new StreamObserver<>() {
            private final List<String> createdIds = new ArrayList<>();
 
            @Override
            public void onNext(CreateUserRequest request) {
                User user = userRepository.save(
                    new User(request.getName(), request.getEmail())
                );
                createdIds.add(user.getUserId());
            }
 
            @Override
            public void onError(Throwable t) {
                responseObserver.onError(t);
            }
 
            @Override
            public void onCompleted() {
                responseObserver.onNext(
                    CreateUsersResponse.newBuilder()
                        .addAllUserIds(createdIds)
                        .build()
                );
                responseObserver.onCompleted();
            }
        };
    }
}

# application.yml (Spring Boot)
dubbo:
  application:
    name: user-service
    logger: slf4j
    qos-enable: false
 
  protocol:
    name: tri  # Triple 协议
    port: 50051
    serialization: protobuf
 
  registry:
    address: nacos://nacos.example.com:8848
    parameters:
      namespace: production
      group: dubbo-services
 
  config-center:
    address: nacos://nacos.example.com:8848
    namespace: production
 
  metadata-report:
    address: nacos://nacos.example.com:8848
 
  consumer:
    check: false
    timeout: 5000
    retries: 2
    loadbalance: roundrobin
 
  provider:
    timeout: 5000
    threads: 200
    executes: 100
 
  # 服务网格集成
  mesh:
    enabled: true
    mode: sidecar  # 或 ambient

// Dubbo 服务端，gRPC 客户端调用
// Dubbo 服务自动暴露 gRPC 端点
 
// gRPC 客户端代码
public class GrpcClient {
 
    private final UserServiceGrpc.UserServiceBlockingStub stub;
 
    public GrpcClient() {
        ManagedChannel channel = ManagedChannelBuilder
            .forAddress("user-service.dubbo.svc.cluster.local", 50051)
            .usePlaintext()
            .build();
        this.stub = UserServiceGrpc.newBlockingStub(channel);
    }
 
    public User getUser(String userId) {
        return stub.getUser(
            GetUserRequest.newBuilder()
                .setUserId(userId)
                .build()
        );
    }
}

// 消费者端契约测试
@Provider("UserService")
@PactFolder("pacts")
public class UserServiceConsumerTest {
 
    @Pact(consumer = "OrderService")
    public RequestResponsePact getUserPact(PactDslWithProvider builder) {
        return builder
            .given("user exists with id 123")
            .uponReceiving("a request to get user")
            .path("/api/v1/users/123")
            .method("GET")
            .headers(Map.of("Authorization", "Bearer token"))
            .willRespondWith()
            .status(200)
            .headers(Map.of("Content-Type", "application/json"))
            .body(new PactDslJsonBody()
                .stringType("userId", "123")
                .stringType("name", "John Doe")
                .stringType("email", "john@example.com")
                .stringValue("status", "ACTIVE")
            )
            .toPact();
    }
 
    @Test
    @PactTestFor(pactMethod = "getUserPact")
    public void testGetUser(MockServer mockServer) {
        // 使用 Mock Server 测试消费者逻辑
        UserServiceClient client = new UserServiceClient(mockServer.getUrl());
        User user = client.getUser("123");
 
        assertThat(user.getUserId()).isEqualTo("123");
        assertThat(user.getName()).isEqualTo("John Doe");
    }
}

// 提供者端契约验证
@Provider("UserService")
@PactBroker(url = "${PACT_BROKER_URL}",
            authentication = @PactBrokerAuth(token = "${PACT_BROKER_TOKEN}"))
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
public class UserServiceProviderTest {
 
    @TestTemplate
    @ExtendWith(PactVerificationSpringProvider.class)
    void pactVerificationTestTemplate(PactVerificationContext context) {
        context.verifyInteraction();
    }
 
    @State("user exists with id 123")
    void userExists() {
        // 设置测试数据
        userRepository.save(new User("123", "John Doe", "john@example.com"));
    }
}

# pact-broker.yml (Kubernetes Deployment)
apiVersion: apps/v1
kind: Deployment
metadata:
  name: pact-broker
spec:
  template:
    spec:
      containers:
        - name: pact-broker
          image: pactfoundation/pact-broker:2.108.0
          env:
            - name: PACT_BROKER_DATABASE_URL
              value: "postgres://pact:pact@postgres:5432/pact"
            - name: PACT_BROKER_BASIC_AUTH_USERNAME
              valueFrom:
                secretKeyRef:
                  name: pact-broker-auth
                  key: username
            - name: PACT_BROKER_BASIC_AUTH_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: pact-broker-auth
                  key: password

// 契约定义 (contracts/user-service/shouldReturnUser.groovy)
Contract.make {
    description "Should return user by ID"
    request {
        method GET()
        url "/api/v1/users/123"
        headers {
            header("Authorization", "Bearer token")
        }
    }
    response {
        status 200
        headers {
            header("Content-Type", "application/json")
        }
        body([
            userId: "123",
            name: "John Doe",
            email: "john@example.com",
            status: "ACTIVE"
        ])
    }
}

# Spring Cloud Contract 配置
spring:
  cloud:
    contract:
      verifier:
        enabled: true
        base-package-for-tests: com.example.contract
        base-class-for-tests: com.example.BaseContractTest

# OpenAPI 版本管理示例
openapi: 3.1.0
info:
  title: 用户服务 API
  version: 2.1.0
  x-api-deprecated: false
  x-api-sunset: "2026-12-31"  # 废弃日期
 
paths:
  /v2/users:
    get:
      operationId: listUsersV2
      summary: 获取用户列表（v2）
      # ...
 
  /v1/users:
    get:
      operationId: listUsersV1
      summary: 获取用户列表（v1 - 已废弃）
      deprecated: true
      x-deprecation-date: "2025-06-01"
      x-sunset-date: "2026-06-01"
      responses:
        '200':
          # ...
        '410':
          description: API 已下线，请迁移至 v2