28e - 微服务与 Serverless

架构选择决策树：

你的项目处于什么阶段？
│
├── MVP / 早期创业（< 5 人团队）
│   └── 单体优先（Modular Monolith）
│       ├── 用 AI 生成模块化的单体架构
│       └── 预留微服务拆分的边界（DDD 模块）
│
├── 成长期（5-20 人团队，明确的领域边界）
│   ├── 核心域独立性要求高？
│   │   └── 微服务（按 Bounded Context 拆分）
│   ├── 流量波动大，按需计费？
│   │   └── Serverless（事件驱动函数）
│   └── 混合需求？
│       └── 微服务 + Serverless 混合架构
│
└── 成熟期（20+ 人团队，多团队协作）
    └── 微服务 + 平台工程
        ├── 每个团队拥有 1-3 个服务
        └── 内部开发者平台（IDP）统一管理

DDD 核心概念与微服务映射：

┌─────────────────────────────────────────────────────────────┐
│                    业务领域（Domain）                         │
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ Bounded      │  │ Bounded      │  │ Bounded      │      │
│  │ Context A    │  │ Context B    │  │ Context C    │      │
│  │              │  │              │  │              │      │
│  │ ┌──────────┐ │  │ ┌──────────┐ │  │ ┌──────────┐ │      │
│  │ │ 聚合根 A1 │ │  │ │ 聚合根 B1 │ │  │ │ 聚合根 C1 │ │      │
│  │ │ ├─实体    │ │  │ │ ├─实体    │ │  │ │ ├─实体    │ │      │
│  │ │ └─值对象  │ │  │ │ └─值对象  │ │  │ │ └─值对象  │ │      │
│  │ └──────────┘ │  │ └──────────┘ │  │ └──────────┘ │      │
│  │              │  │              │  │              │      │
│  │  → 微服务 A  │  │  → 微服务 B  │  │  → 微服务 C  │      │
│  │  独立数据库   │  │  独立数据库   │  │  独立数据库   │      │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘      │
│         │                 │                 │               │
│         └────── API / 事件 ─┴────── API / 事件 ┘               │
│                                                             │
│  关键原则：                                                   │
│  • 每个 Bounded Context = 一个微服务                          │
│  • 每个微服务拥有自己的数据库（Database per Service）           │
│  • 服务间通过 API 或事件通信，不共享数据库                      │
│  • 同一概念在不同 Context 中可以有不同含义                      │
│    （如"用户"在认证服务是 Credential，在订单服务是 Customer）   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

你是一位领域驱动设计（DDD）专家。请分析以下业务领域，识别 Bounded Context 并建议微服务拆分方案。

## 业务描述
[详细描述你的业务领域、核心流程、用户角色]

## 分析要求
1. 识别核心域（Core Domain）、支撑域（Supporting Domain）、通用域（Generic Domain）
2. 为每个域定义 Bounded Context，说明：
   - 上下文名称和职责
   - 核心聚合根（Aggregate Root）
   - 关键实体和值对象
   - 领域事件（Domain Events）
3. 绘制上下文映射图（Context Map），标注关系类型：
   - 合作关系（Partnership）
   - 客户-供应商（Customer-Supplier）
   - 防腐层（Anti-Corruption Layer）
   - 开放主机服务（Open Host Service）
   - 共享内核（Shared Kernel）
4. 建议每个 Bounded Context 对应的微服务
5. 标注哪些服务可以合并（避免过度拆分）

## 约束条件
- 团队规模：[人数]
- 预期 QPS：[数值]
- 数据一致性要求：[强一致/最终一致]

## 输出格式
1. 领域分析表（域类型、Bounded Context、聚合根、领域事件）
2. 上下文映射图（Mermaid 格式）
3. 微服务拆分建议（服务名、职责、数据库、通信方式）
4. 拆分风险评估（哪些拆分可能过度，建议合并的理由）

服务边界验证清单：

✅ 独立性检查
  □ 该服务能否独立部署，不影响其他服务？
  □ 该服务能否独立扩缩容？
  □ 该服务的数据库能否独立迁移？

✅ 内聚性检查
  □ 服务内的所有功能是否围绕同一业务能力？
  □ 是否存在"上帝服务"（承担过多职责）？
  □ 修改一个业务规则是否只需要改一个服务？

✅ 耦合度检查
  □ 服务间是否存在循环依赖？
  □ 一个请求是否需要调用超过 3 个服务？（如果是，考虑合并）
  □ 服务间是否共享数据库表？（如果是，边界有问题）

✅ 团队对齐检查
  □ 每个服务是否可以由一个小团队（2-8 人）独立维护？
  □ 服务边界是否与团队边界对齐？（康威定律）

✅ 数据所有权检查
  □ 每条数据是否有且只有一个服务拥有？
  □ 其他服务是否通过 API 或事件获取数据副本？
  □ 是否存在跨服务的事务需求？（如果是，考虑 Saga 模式）

你是一位微服务架构师。请为以下微服务生成项目骨架代码。

## 服务信息
- 服务名称：[服务名]
- Bounded Context：[上下文描述]
- 核心聚合根：[聚合根列表]
- 领域事件：[事件列表]

## 技术栈
- 语言/框架：[例如 TypeScript + NestJS / Go + Gin / Python + FastAPI]
- 数据库：[例如 PostgreSQL / MongoDB]
- 消息队列：[例如 RabbitMQ / Kafka / NATS]
- API 风格：[REST / gRPC / 混合]

## 项目结构要求
采用六边形架构（Hexagonal Architecture）：

## 必须包含
1. 领域实体和聚合根（含业务规则验证）
2. 仓储接口和内存实现（用于测试）
3. 至少一个命令处理器和查询处理器
4. 领域事件定义和发布机制
5. REST API 端点（CRUD + 业务操作）
6. Docker 配置（Dockerfile + docker-compose.yml）
7. 单元测试骨架

通信方式选择决策树：

调用方需要立即获得结果吗？
│
├── 是（同步）
│   ├── 内部服务间通信？
│   │   ├── 高性能要求（< 5ms）→ gRPC
│   │   └── 简单 CRUD → REST
│   └── 外部客户端？
│       ├── 多服务数据聚合 → GraphQL Federation
│       └── 单服务调用 → REST
│
└── 否（异步）
    ├── 需要消息持久化和重放？
    │   └── Kafka（事件流）
    ├── 需要复杂路由（topic/fanout）？
    │   └── RabbitMQ
    ├── 需要轻量级、低延迟？
    │   └── NATS
    └── 需要实时双向通信？
        └── WebSocket / SSE

你是一位微服务后端专家。请为 [服务A] 生成调用 [服务B] 的类型安全 HTTP 客户端。

## 服务 B 的 API 端点
[列出服务 B 的 API 端点、请求/响应类型]

## 技术要求
- 语言：TypeScript
- HTTP 客户端：[fetch / axios / ky / got]
- 重试策略：指数退避，最多 3 次
- 超时：[例如 5 秒]
- 断路器：[是/否]

## 必须包含
1. 请求/响应的 TypeScript 类型定义
2. 统一的错误处理（网络错误、超时、4xx、5xx）
3. 请求重试逻辑（仅对幂等操作重试）
4. 请求日志（不记录敏感信息）
5. 请求追踪（传递 trace-id header）
6. 健康检查端点调用
7. 连接池配置（如适用）

// ============================================
// clients/order-service.client.ts
// 订单服务 → 库存服务的 HTTP 客户端
// ============================================
 
interface InventoryCheckRequest {
  productId: string;
  quantity: number;
}
 
interface InventoryCheckResponse {
  available: boolean;
  currentStock: number;
  reservationId?: string;
}
 
interface ServiceClientConfig {
  baseUrl: string;
  timeout: number;
  retries: number;
  circuitBreaker: {
    threshold: number;      // 失败阈值（触发熔断）
    resetTimeout: number;   // 熔断恢复时间（ms）
  };
}
 
class InventoryServiceClient {
  private failures = 0;
  private circuitOpen = false;
  private circuitOpenTime = 0;
 
  constructor(private readonly config: ServiceClientConfig) {}
 
  /**
   * 检查库存可用性
   * 通信要点：
   * 1. 传递 trace-id 实现分布式追踪
   * 2. 设置合理超时（避免级联超时）
   * 3. 幂等操作自动重试
   * 4. 断路器防止级联故障
   */
  async checkAvailability(
    request: InventoryCheckRequest,
    traceId: string,
  ): Promise<InventoryCheckResponse> {
    // 断路器检查
    if (this.isCircuitOpen()) {
      throw new ServiceUnavailableError(
        'inventory-service',
        '库存服务暂时不可用（断路器已打开）',
      );
    }
 
    const url = `${this.config.baseUrl}/api/v1/inventory/check`;
 
    for (let attempt = 1; attempt <= this.config.retries; attempt++) {
      try {
        const controller = new AbortController();
        const timeoutId = setTimeout(
          () => controller.abort(),
          this.config.timeout,
        );
 
        const response = await fetch(url, {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
            'X-Trace-Id': traceId,
            'X-Source-Service': 'order-service',
          },
          body: JSON.stringify(request),
          signal: controller.signal,
        });
 
        clearTimeout(timeoutId);
 
        if (!response.ok) {
          // 4xx 错误不重试（客户端错误）
          if (response.status >= 400 && response.status < 500) {
            const error = await response.json();
            throw new ClientError(response.status, error.message);
          }
          // 5xx 错误重试
          throw new ServerError(response.status, 'inventory-service');
        }
 
        // 成功：重置断路器计数
        this.resetCircuitBreaker();
        return await response.json() as InventoryCheckResponse;
 
      } catch (error) {
        if (error instanceof ClientError) throw error; // 不重试
 
        // 记录失败
        this.recordFailure();
 
        if (attempt === this.config.retries) {
          throw new ServiceUnavailableError(
            'inventory-service',
            `库存服务调用失败（已重试 ${this.config.retries} 次）`,
          );
        }
 
        // 指数退避等待
        const delay = Math.min(1000 * Math.pow(2, attempt - 1), 5000);
        await new Promise(resolve => setTimeout(resolve, delay));
      }
    }
 
    throw new ServiceUnavailableError('inventory-service', '未知错误');
  }
 
  private isCircuitOpen(): boolean {
    if (!this.circuitOpen) return false;
    // 半开状态：超过恢复时间后允许一次尝试
    if (Date.now() - this.circuitOpenTime > this.config.circuitBreaker.resetTimeout) {
      this.circuitOpen = false;
      this.failures = 0;
      return false;
    }
    return true;
  }
 
  private recordFailure(): void {
    this.failures++;
    if (this.failures >= this.config.circuitBreaker.threshold) {
      this.circuitOpen = true;
      this.circuitOpenTime = Date.now();
    }
  }
 
  private resetCircuitBreaker(): void {
    this.failures = 0;
    this.circuitOpen = false;
  }
}

你是一位 gRPC 专家。请为以下微服务间通信生成 Protocol Buffers 定义和服务实现。

## 通信需求
- 调用方服务：[服务名]
- 被调用服务：[服务名]
- 通信场景：[描述具体的通信需求]

## 技术栈
- 语言：[TypeScript / Go / Python / Java]
- gRPC 框架：[nice-grpc / grpc-go / grpcio / grpc-java]
- Protobuf 管理：[Buf / protoc]

## 要求
1. .proto 文件定义（包含 service、message、enum）
2. 服务端实现（包含错误处理和日志）
3. 客户端实现（包含重试和超时）
4. 使用 Buf 的 lint 规则确保 API 质量
5. 包含健康检查服务（grpc.health.v1）
6. 支持 deadline 传播（上游超时传递给下游）

## gRPC 通信模式
- [ ] Unary RPC（一请求一响应）
- [ ] Server Streaming（服务端流式响应）
- [ ] Client Streaming（客户端流式请求）
- [ ] Bidirectional Streaming（双向流式）

// ============================================
// proto/inventory/v1/inventory.proto
// 库存服务 gRPC 接口定义
// ============================================
 
syntax = "proto3";
 
package inventory.v1;
 
option go_package = "github.com/myapp/inventory/v1;inventoryv1";
 
// 库存服务
service InventoryService {
  // 检查库存可用性（Unary RPC）
  rpc CheckAvailability(CheckAvailabilityRequest)
    returns (CheckAvailabilityResponse);
 
  // 预留库存（Unary RPC）
  rpc ReserveStock(ReserveStockRequest)
    returns (ReserveStockResponse);
 
  // 释放预留（Unary RPC）
  rpc ReleaseReservation(ReleaseReservationRequest)
    returns (ReleaseReservationResponse);
 
  // 批量查询库存（Server Streaming）
  rpc BatchCheckAvailability(BatchCheckRequest)
    returns (stream CheckAvailabilityResponse);
}
 
message CheckAvailabilityRequest {
  string product_id = 1;
  int32 quantity = 2;
}
 
message CheckAvailabilityResponse {
  bool available = 1;
  int32 current_stock = 2;
  string reservation_id = 3;  // 可选：预留 ID
}
 
message ReserveStockRequest {
  string product_id = 1;
  int32 quantity = 2;
  string order_id = 3;        // 关联订单 ID（幂等键）
  int32 ttl_seconds = 4;      // 预留有效期
}
 
message ReserveStockResponse {
  string reservation_id = 1;
  google.protobuf.Timestamp expires_at = 2;
}
 
message ReleaseReservationRequest {
  string reservation_id = 1;
}
 
message ReleaseReservationResponse {
  bool success = 1;
}
 
message BatchCheckRequest {
  repeated CheckAvailabilityRequest items = 1;
}

// ============================================
// clients/inventory_client.go
// 订单服务中的库存 gRPC 客户端
// ============================================
 
package clients
 
import (
    "context"
    "time"
 
    inventoryv1 "github.com/myapp/inventory/v1"
    "google.golang.org/grpc"
    "google.golang.org/grpc/codes"
    "google.golang.org/grpc/credentials/insecure"
    "google.golang.org/grpc/metadata"
    "google.golang.org/grpc/status"
)
 
type InventoryClient struct {
    client inventoryv1.InventoryServiceClient
    conn   *grpc.ClientConn
}
 
func NewInventoryClient(addr string) (*InventoryClient, error) {
    conn, err := grpc.NewClient(addr,
        grpc.WithTransportCredentials(insecure.NewCredentials()),
        // 重试策略
        grpc.WithDefaultServiceConfig(`{
            "methodConfig": [{
                "name": [{"service": "inventory.v1.InventoryService"}],
                "retryPolicy": {
                    "maxAttempts": 3,
                    "initialBackoff": "0.1s",
                    "maxBackoff": "1s",
                    "backoffMultiplier": 2,
                    "retryableStatusCodes": ["UNAVAILABLE", "DEADLINE_EXCEEDED"]
                }
            }]
        }`),
    )
    if err != nil {
        return nil, err
    }
 
    return &InventoryClient{
        client: inventoryv1.NewInventoryServiceClient(conn),
        conn:   conn,
    }, nil
}
 
// CheckAvailability 检查库存
// 通信要点：
// 1. 设置 deadline（超时传播）
// 2. 传递 trace-id（分布式追踪）
// 3. 处理 gRPC 状态码
func (c *InventoryClient) CheckAvailability(
    ctx context.Context,
    productID string,
    quantity int32,
    traceID string,
) (*inventoryv1.CheckAvailabilityResponse, error) {
    // 设置 deadline（如果上游没有设置）
    if _, ok := ctx.Deadline(); !ok {
        var cancel context.CancelFunc
        ctx, cancel = context.WithTimeout(ctx, 3*time.Second)
        defer cancel()
    }
 
    // 传递追踪信息
    ctx = metadata.AppendToOutgoingContext(ctx,
        "x-trace-id", traceID,
        "x-source-service", "order-service",
    )
 
    resp, err := c.client.CheckAvailability(ctx,
        &inventoryv1.CheckAvailabilityRequest{
            ProductId: productID,
            Quantity:  quantity,
        },
    )
    if err != nil {
        return nil, c.handleError(err)
    }
 
    return resp, nil
}
 
func (c *InventoryClient) handleError(err error) error {
    st, ok := status.FromError(err)
    if !ok {
        return fmt.Errorf("inventory service: unknown error: %w", err)
    }
 
    switch st.Code() {
    case codes.NotFound:
        return ErrProductNotFound
    case codes.ResourceExhausted:
        return ErrInsufficientStock
    case codes.DeadlineExceeded:
        return ErrServiceTimeout
    case codes.Unavailable:
        return ErrServiceUnavailable
    default:
        return fmt.Errorf("inventory service: %s", st.Message())
    }
}
 
func (c *InventoryClient) Close() error {
    return c.conn.Close()
}

你是一位事件驱动架构专家。请为以下微服务间的异步通信生成代码。

## 通信场景
- 事件生产者：[服务名]
- 事件消费者：[服务名列表]
- 业务场景：[描述事件触发条件和消费者行为]

## 技术栈
- 消息队列：[RabbitMQ / Kafka / NATS]
- 语言：[TypeScript / Go / Python]
- 序列化：[JSON / Protobuf / Avro]

## 要求
1. 事件 Schema 定义（包含版本号、时间戳、trace-id）
2. 事件生产者（发布事件，确保至少一次投递）
3. 事件消费者（消费事件，实现幂等处理）
4. 死信队列（DLQ）处理失败消息
5. 消息重试策略（指数退避，最多 5 次）
6. 消费者组配置（多实例并行消费）
7. 事件 Schema 演进策略（向后兼容）

## 幂等性要求
消费者必须实现幂等处理：
- 使用事件 ID 去重
- 使用数据库唯一约束防止重复处理
- 处理乱序消息的策略

// ============================================
// events/order-events.ts —— 领域事件定义
// ============================================
 
// 事件基类：所有领域事件的标准结构
interface DomainEvent<T = unknown> {
  eventId: string;          // 唯一事件 ID（UUID）
  eventType: string;        // 事件类型
  version: number;          // Schema 版本（用于演进）
  timestamp: string;        // ISO 8601 时间戳
  traceId: string;          // 分布式追踪 ID
  source: string;           // 来源服务
  data: T;                  // 事件数据
}
 
// 订单已创建事件
interface OrderCreatedEvent extends DomainEvent<{
  orderId: string;
  customerId: string;
  items: Array<{
    productId: string;
    quantity: number;
    unitPrice: number;
  }>;
  totalAmount: number;
}> {
  eventType: 'order.created';
  version: 1;
}
 
// 订单已支付事件
interface OrderPaidEvent extends DomainEvent<{
  orderId: string;
  paymentId: string;
  amount: number;
  paidAt: string;
}> {
  eventType: 'order.paid';
  version: 1;
}

// ============================================
// messaging/event-publisher.ts —— 事件发布者
// ============================================
 
import amqp from 'amqplib';
import { randomUUID } from 'crypto';
 
class EventPublisher {
  private channel: amqp.Channel | null = null;
 
  constructor(
    private readonly connectionUrl: string,
    private readonly exchange: string = 'domain-events',
  ) {}
 
  async connect(): Promise<void> {
    const connection = await amqp.connect(this.connectionUrl);
    this.channel = await connection.createChannel();
 
    // 声明 topic 交换器（支持路由键模式匹配）
    await this.channel.assertExchange(this.exchange, 'topic', {
      durable: true,  // 持久化交换器
    });
  }
 
  /**
   * 发布领域事件
   * 可靠性要点：
   * 1. 消息持久化（deliveryMode: 2）
   * 2. 使用 confirm 模式确保消息到达 broker
   * 3. 路由键格式：{aggregate}.{event}（如 order.created）
   */
  async publish<T>(event: DomainEvent<T>): Promise<void> {
    if (!this.channel) throw new Error('Publisher not connected');
 
    const routingKey = event.eventType; // e.g., "order.created"
    const message = Buffer.from(JSON.stringify(event));
 
    this.channel.publish(this.exchange, routingKey, message, {
      persistent: true,         // 消息持久化
      messageId: event.eventId, // 用于去重
      timestamp: Date.now(),
      headers: {
        'x-trace-id': event.traceId,
        'x-event-version': event.version,
        'x-source-service': event.source,
      },
    });
  }
 
  // 辅助方法：创建标准事件
  createEvent<T>(
    eventType: string,
    data: T,
    traceId: string,
  ): DomainEvent<T> {
    return {
      eventId: randomUUID(),
      eventType,
      version: 1,
      timestamp: new Date().toISOString(),
      traceId,
      source: process.env.SERVICE_NAME ?? 'unknown',
      data,
    };
  }
}

// ============================================
// messaging/event-consumer.ts —— 事件消费者
// ============================================
 
import amqp from 'amqplib';
 
interface ConsumerConfig {
  queue: string;              // 队列名
  routingKeys: string[];      // 订阅的路由键模式
  prefetch: number;           // 预取数量（并发控制）
  maxRetries: number;         // 最大重试次数
}
 
class EventConsumer {
  private channel: amqp.Channel | null = null;
 
  constructor(
    private readonly connectionUrl: string,
    private readonly exchange: string = 'domain-events',
    private readonly config: ConsumerConfig,
  ) {}
 
  async connect(): Promise<void> {
    const connection = await amqp.connect(this.connectionUrl);
    this.channel = await connection.createChannel();
 
    // 设置预取（控制并发消费数量）
    await this.channel.prefetch(this.config.prefetch);
 
    // 声明队列
    await this.channel.assertQueue(this.config.queue, {
      durable: true,
      arguments: {
        // 死信队列配置
        'x-dead-letter-exchange': `${this.exchange}.dlx`,
        'x-dead-letter-routing-key': this.config.queue,
      },
    });
 
    // 声明死信交换器和队列
    await this.channel.assertExchange(`${this.exchange}.dlx`, 'direct', {
      durable: true,
    });
    await this.channel.assertQueue(`${this.config.queue}.dlq`, {
      durable: true,
    });
    await this.channel.bindQueue(
      `${this.config.queue}.dlq`,
      `${this.exchange}.dlx`,
      this.config.queue,
    );
 
    // 绑定路由键
    for (const key of this.config.routingKeys) {
      await this.channel.bindQueue(
        this.config.queue,
        this.exchange,
        key,
      );
    }
  }
 
  /**
   * 开始消费事件
   * 可靠性要点：
   * 1. 手动 ACK（处理成功后确认）
   * 2. 幂等处理（通过 eventId 去重）
   * 3. 重试机制（通过 header 计数）
   * 4. 死信队列（超过重试次数的消息）
   */
  async consume(
    handler: (event: DomainEvent) => Promise<void>,
    isProcessed: (eventId: string) => Promise<boolean>,
  ): Promise<void> {
    if (!this.channel) throw new Error('Consumer not connected');
 
    await this.channel.consume(this.config.queue, async (msg) => {
      if (!msg) return;
 
      try {
        const event: DomainEvent = JSON.parse(msg.content.toString());
 
        // 幂等检查：跳过已处理的事件
        if (await isProcessed(event.eventId)) {
          this.channel!.ack(msg);
          return;
        }
 
        // 处理事件
        await handler(event);
 
        // 处理成功：确认消息
        this.channel!.ack(msg);
 
      } catch (error) {
        // 检查重试次数
        const retryCount = (msg.properties.headers?.['x-retry-count'] ?? 0) as number;
 
        if (retryCount >= this.config.maxRetries) {
          // 超过重试次数：发送到死信队列
          this.channel!.nack(msg, false, false);
        } else {
          // 重试：重新发布消息（带递增的重试计数）
          const delay = Math.min(1000 * Math.pow(2, retryCount), 30000);
          setTimeout(() => {
            this.channel!.publish(this.exchange, msg.fields.routingKey, msg.content, {
              ...msg.properties,
              headers: {
                ...msg.properties.headers,
                'x-retry-count': retryCount + 1,
              },
            });
            this.channel!.ack(msg);
          }, delay);
        }
      }
    });
  }
}

Serverless 平台选择决策树：

你的主要需求是什么？
│
├── 极低延迟（< 10ms 冷启动）
│   └── Cloudflare Workers / Deno Deploy
│       适合：边缘 API、A/B 测试、地理路由
│
├── Next.js / 前端配套
│   └── Vercel Functions
│       适合：API Routes、ISR、Middleware
│
├── AWS 生态集成
│   └── AWS Lambda
│       适合：S3 触发、DynamoDB 流、SQS 消费
│
├── 数据库触发 / Supabase 生态
│   └── Supabase Edge Functions
│       适合：数据库 Webhook、RLS 辅助逻辑
│
└── 长时间运行任务
    └── AWS Lambda（15min）/ GCF v2（60min）
        适合：数据处理、报告生成、批量操作

你是一位 Serverless 架构专家。请为以下需求生成 Serverless 函数代码。

## 函数需求
- 功能描述：[描述函数的业务逻辑]
- 触发方式：[HTTP / 定时 / 事件（S3/SQS/DynamoDB Stream）]
- 输入：[请求格式或事件格式]
- 输出：[响应格式]

## 目标平台
- 平台：[AWS Lambda / Vercel / Cloudflare Workers / Supabase Edge]
- 运行时：[Node.js 20 / Python 3.12 / Go 1.22 / Rust]
- 框架：[SST / Serverless Framework / 原生 / Hono]

## 性能要求
- 冷启动目标：[例如 < 200ms]
- 执行时间目标：[例如 < 3s]
- 内存配置：[例如 256MB]

## 必须包含
1. 输入验证（使用 [Zod / Pydantic]）
2. 错误处理（统一错误响应格式）
3. 日志记录（结构化 JSON 日志）
4. 环境变量配置（不硬编码密钥）
5. 冷启动优化（连接复用、延迟初始化）
6. CORS 配置（如果是 HTTP 触发）
7. 部署配置文件

## 冷启动优化要求
- 数据库连接在 handler 外部初始化（连接复用）
- 最小化依赖包大小
- 使用 tree-shaking 和 bundling
- 避免在初始化阶段做不必要的 I/O

// ============================================
// functions/process-order.ts —— AWS Lambda 订单处理函数
// 使用 SST (Serverless Stack) 框架
// ============================================
 
import { APIGatewayProxyHandlerV2 } from 'aws-lambda';
import { z } from 'zod';
 
// ---- 冷启动优化：在 handler 外部初始化 ----
// 数据库连接在 Lambda 容器生命周期内复用
import { PrismaClient } from '@prisma/client';
 
const prisma = new PrismaClient({
  // Lambda 优化：减少连接池大小
  datasources: {
    db: { url: process.env.DATABASE_URL },
  },
});
 
// ---- 输入验证 Schema ----
const CreateOrderSchema = z.object({
  customerId: z.string().uuid(),
  items: z.array(z.object({
    productId: z.string().uuid(),
    quantity: z.number().int().positive().max(100),
  })).min(1).max(50),
  shippingAddress: z.object({
    street: z.string().min(1).max(200),
    city: z.string().min(1).max(100),
    zipCode: z.string().regex(/^\d{5,6}$/),
    country: z.string().length(2), // ISO 3166-1 alpha-2
  }),
});
 
// ---- Lambda Handler ----
export const handler: APIGatewayProxyHandlerV2 = async (event) => {
  const requestId = event.requestContext?.requestId ?? 'unknown';
 
  try {
    // 1. 解析和验证输入
    const body = JSON.parse(event.body ?? '{}');
    const input = CreateOrderSchema.parse(body);
 
    // 2. 业务逻辑
    const order = await prisma.$transaction(async (tx) => {
      // 检查库存
      for (const item of input.items) {
        const product = await tx.product.findUnique({
          where: { id: item.productId },
        });
        if (!product || product.stock < item.quantity) {
          throw new BusinessError(
            'INSUFFICIENT_STOCK',
            `商品 ${item.productId} 库存不足`,
          );
        }
      }
 
      // 创建订单
      const order = await tx.order.create({
        data: {
          customerId: input.customerId,
          status: 'PENDING',
          items: {
            create: input.items.map(item => ({
              productId: item.productId,
              quantity: item.quantity,
            })),
          },
          shippingAddress: input.shippingAddress,
        },
        include: { items: true },
      });
 
      // 扣减库存
      for (const item of input.items) {
        await tx.product.update({
          where: { id: item.productId },
          data: { stock: { decrement: item.quantity } },
        });
      }
 
      return order;
    });
 
    // 3. 结构化日志
    console.log(JSON.stringify({
      level: 'info',
      message: 'Order created',
      requestId,
      orderId: order.id,
      customerId: input.customerId,
      itemCount: input.items.length,
    }));
 
    // 4. 返回响应
    return {
      statusCode: 201,
      headers: {
        'Content-Type': 'application/json',
        'X-Request-Id': requestId,
      },
      body: JSON.stringify({
        orderId: order.id,
        status: order.status,
        createdAt: order.createdAt,
      }),
    };
 
  } catch (error) {
    // 统一错误处理
    if (error instanceof z.ZodError) {
      return {
        statusCode: 400,
        body: JSON.stringify({
          error: 'VALIDATION_ERROR',
          details: error.errors,
        }),
      };
    }
 
    if (error instanceof BusinessError) {
      return {
        statusCode: 422,
        body: JSON.stringify({
          error: error.code,
          message: error.message,
        }),
      };
    }
 
    // 未知错误：记录日志但不暴露内部信息
    console.error(JSON.stringify({
      level: 'error',
      message: 'Unhandled error',
      requestId,
      error: error instanceof Error ? error.message : 'Unknown',
      stack: error instanceof Error ? error.stack : undefined,
    }));
 
    return {
      statusCode: 500,
      body: JSON.stringify({
        error: 'INTERNAL_ERROR',
        message: '服务器内部错误',
        requestId,
      }),
    };
  }
};
 
class BusinessError extends Error {
  constructor(
    public readonly code: string,
    message: string,
  ) {
    super(message);
    this.name = 'BusinessError';
  }
}

// ============================================
// src/worker.ts —— Cloudflare Workers API
// 使用 Hono 框架（轻量级，适合 Workers）
// ============================================
 
import { Hono } from 'hono';
import { cors } from 'hono/cors';
import { zValidator } from '@hono/zod-validator';
import { z } from 'zod';
 
// Cloudflare Workers 环境绑定类型
type Bindings = {
  DB: D1Database;              // Cloudflare D1 数据库
  KV: KVNamespace;             // Cloudflare KV 存储
  RATE_LIMITER: RateLimit;     // 速率限制
  API_KEY: string;             // 环境变量
};
 
const app = new Hono<{ Bindings: Bindings }>();
 
// 中间件
app.use('*', cors({
  origin: ['https://yourdomain.com'],
  allowMethods: ['GET', 'POST', 'PUT', 'DELETE'],
}));
 
// 速率限制中间件
app.use('/api/*', async (c, next) => {
  const ip = c.req.header('CF-Connecting-IP') ?? 'unknown';
  const { success } = await c.env.RATE_LIMITER.limit({
    key: ip,
  });
  if (!success) {
    return c.json({ error: 'RATE_LIMITED' }, 429);
  }
  await next();
});
 
// ---- API 端点 ----
 
const ProductSchema = z.object({
  name: z.string().min(1).max(200),
  price: z.number().positive(),
  category: z.string().min(1),
});
 
// 创建产品
app.post(
  '/api/products',
  zValidator('json', ProductSchema),
  async (c) => {
    const input = c.req.valid('json');
 
    // 使用 Cloudflare D1（SQLite 边缘数据库）
    const result = await c.env.DB.prepare(
      'INSERT INTO products (name, price, category) VALUES (?, ?, ?) RETURNING *'
    )
      .bind(input.name, input.price, input.category)
      .first();
 
    // 缓存失效
    await c.env.KV.delete('products:list');
 
    return c.json(result, 201);
  },
);
 
// 获取产品列表（带 KV 缓存）
app.get('/api/products', async (c) => {
  // 先查 KV 缓存
  const cached = await c.env.KV.get('products:list', 'json');
  if (cached) {
    return c.json(cached);
  }
 
  // 缓存未命中：查数据库
  const { results } = await c.env.DB.prepare(
    'SELECT * FROM products ORDER BY created_at DESC LIMIT 100'
  ).all();
 
  // 写入缓存（TTL 60 秒）
  await c.env.KV.put('products:list', JSON.stringify(results), {
    expirationTtl: 60,
  });
 
  return c.json(results);
});
 
export default app;

// ============================================
// app/api/webhooks/stripe/route.ts
// Next.js App Router + Vercel Serverless Function
// Stripe Webhook 处理
// ============================================
 
import { NextRequest, NextResponse } from 'next/server';
import Stripe from 'stripe';
 
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: '2024-12-18.acacia',
});
 
const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET!;
 
export async function POST(request: NextRequest) {
  const body = await request.text();
  const signature = request.headers.get('stripe-signature')!;
 
  let event: Stripe.Event;
 
  try {
    // 验证 Webhook 签名（防止伪造）
    event = stripe.webhooks.constructEvent(body, signature, webhookSecret);
  } catch (err) {
    console.error('Webhook signature verification failed');
    return NextResponse.json(
      { error: 'Invalid signature' },
      { status: 400 },
    );
  }
 
  // 幂等处理：检查事件是否已处理
  const processed = await checkEventProcessed(event.id);
  if (processed) {
    return NextResponse.json({ received: true });
  }
 
  try {
    switch (event.type) {
      case 'checkout.session.completed': {
        const session = event.data.object as Stripe.Checkout.Session;
        await handleCheckoutComplete(session);
        break;
      }
      case 'invoice.payment_succeeded': {
        const invoice = event.data.object as Stripe.Invoice;
        await handlePaymentSucceeded(invoice);
        break;
      }
      case 'customer.subscription.deleted': {
        const subscription = event.data.object as Stripe.Subscription;
        await handleSubscriptionCanceled(subscription);
        break;
      }
      default:
        console.log(`Unhandled event type: ${event.type}`);
    }
 
    // 标记事件已处理
    await markEventProcessed(event.id);
 
    return NextResponse.json({ received: true });
  } catch (error) {
    console.error(`Error processing ${event.type}:`, error);
    // 返回 500 让 Stripe 重试
    return NextResponse.json(
      { error: 'Processing failed' },
      { status: 500 },
    );
  }
}
 
// Vercel 配置：增加 body 大小限制
export const config = {
  api: {
    bodyParser: false, // Stripe 需要原始 body 验证签名
  },
};

冷启动优化清单：

┌─────────────────────────────────────────────────────────────┐
│                  Serverless 冷启动优化策略                     │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. 代码层优化                                               │
│     ├── 最小化依赖包大小（tree-shaking + bundling）           │
│     ├── 使用 esbuild/swc 替代 webpack（构建更快）             │
│     ├── 延迟加载非关键模块（dynamic import）                  │
│     ├── 避免在初始化阶段做 I/O 操作                           │
│     └── 使用轻量级库（如 Hono 替代 Express）                  │
│                                                             │
│  2. 连接层优化                                               │
│     ├── 数据库连接在 handler 外部初始化（连接复用）            │
│     ├── 使用连接池代理（如 PgBouncer、RDS Proxy）             │
│     ├── HTTP 客户端使用 keep-alive                           │
│     └── 缓存 SDK 客户端实例                                  │
│                                                             │
│  3. 平台层优化                                               │
│     ├── AWS Lambda：使用 SnapStart（Java）或 Provisioned      │
│     │   Concurrency（关键路径）                               │
│     ├── AWS Lambda：选择 ARM64 架构（Graviton2，性价比更高）   │
│     ├── Cloudflare Workers：天然低冷启动（V8 Isolate）        │
│     └── Vercel：使用 Edge Runtime（< 50ms 冷启动）           │
│                                                             │
│  4. 架构层优化                                               │
│     ├── 预热策略：定时触发保持实例活跃                         │
│     ├── 异步处理：将耗时操作推到队列                           │
│     ├── 响应流式化：先返回头部，再流式返回 body                │
│     └── 边缘缓存：使用 CDN 缓存减少函数调用                   │
│                                                             │
│  各平台冷启动时间参考（2025）：                                │
│  • Cloudflare Workers：< 5ms（V8 Isolate，无冷启动问题）     │
│  • Deno Deploy：< 10ms                                      │
│  • Vercel Edge：< 50ms                                      │
│  • AWS Lambda (Node.js)：100-300ms（首次）                   │
│  • AWS Lambda (Python)：200-500ms（首次）                    │
│  • AWS Lambda (Java)：1-10s（首次，SnapStart 可降至 200ms）  │
│  • AWS Lambda (Go/Rust)：< 100ms（编译型语言优势）           │
│                                                             │
└─────────────────────────────────────────────────────────────┘

你是一位 Serverless 性能优化专家。请审查以下 Serverless 函数代码，识别冷启动性能问题。

## 代码
[粘贴你的 Serverless 函数代码]

## 目标平台
[AWS Lambda / Cloudflare Workers / Vercel]

## 审查清单
1. **初始化阶段**：handler 外部是否有不必要的 I/O 操作？
2. **依赖大小**：是否引入了不必要的大型依赖？能否用轻量替代？
3. **连接管理**：数据库/HTTP 连接是否在 handler 外部初始化并复用？
4. **延迟加载**：非关键模块是否使用了 dynamic import？
5. **包大小**：部署包大小是否超过推荐值？是否使用了 bundling？
6. **运行时选择**：是否选择了最适合冷启动的运行时？
7. **内存配置**：内存是否配置合理？（Lambda 中更多内存 = 更多 CPU = 更快初始化）

## 输出格式
对每个问题标注影响程度（🔴 严重 / 🟡 中等 / 🟢 轻微），并给出优化建议和预期改善。

你是一位 Docker 和容器化专家。请为以下微服务生成生产级 Dockerfile。

## 服务信息
- 语言/框架：[例如 TypeScript + NestJS / Go + Gin / Python + FastAPI]
- 包管理器：[npm / pnpm / yarn / pip / go mod]
- 构建工具：[esbuild / swc / webpack / none]
- 需要的系统依赖：[例如 sharp 需要 libvips]

## 要求
1. 多阶段构建（builder → runner）
2. 使用 Alpine 或 Distroless 基础镜像（最小化攻击面）
3. 非 root 用户运行（安全加固）
4. 健康检查（HEALTHCHECK 指令）
5. 合理的 .dockerignore
6. 依赖缓存优化（利用 Docker 层缓存）
7. 最终镜像大小目标：< [例如 100MB]
8. 包含 docker-compose.yml（开发环境）

## 安全要求
- 不在镜像中包含 .env 文件或密钥
- 使用固定版本的基础镜像（不用 latest）
- 最小化安装的包（不安装开发依赖）
- 设置只读文件系统（如果可能）

# ============================================
# Dockerfile —— NestJS 微服务（多阶段构建）
# 最终镜像大小目标：< 150MB
# ============================================
 
# ---- 阶段 1：依赖安装 ----
FROM node:20-alpine AS deps
WORKDIR /app
 
# 只复制依赖文件（利用 Docker 层缓存）
COPY package.json pnpm-lock.yaml ./
RUN corepack enable pnpm && pnpm install --frozen-lockfile --prod
 
# ---- 阶段 2：构建 ----
FROM node:20-alpine AS builder
WORKDIR /app
 
COPY package.json pnpm-lock.yaml ./
RUN corepack enable pnpm && pnpm install --frozen-lockfile
 
COPY . .
RUN pnpm build
 
# ---- 阶段 3：生产运行 ----
FROM node:20-alpine AS runner
WORKDIR /app
 
# 安全加固：创建非 root 用户
RUN addgroup --system --gid 1001 appgroup && \
    adduser --system --uid 1001 appuser
 
# 只复制生产依赖和构建产物
COPY --from=deps /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/package.json ./
 
# 设置文件权限
RUN chown -R appuser:appgroup /app
 
# 切换到非 root 用户
USER appuser
 
# 环境变量
ENV NODE_ENV=production
ENV PORT=3000
 
# 暴露端口
EXPOSE 3000
 
# 健康检查
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
 
# 启动命令
CMD ["node", "dist/main.js"]

# ============================================
# docker-compose.yml —— 微服务本地开发环境
# ============================================
 
version: '3.8'
 
services:
  # ---- API 网关 ----
  api-gateway:
    build:
      context: ./services/api-gateway
      dockerfile: Dockerfile.dev
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=development
      - ORDER_SERVICE_URL=http://order-service:3001
      - INVENTORY_SERVICE_URL=http://inventory-service:3002
      - USER_SERVICE_URL=http://user-service:3003
    depends_on:
      - order-service
      - inventory-service
      - user-service
    networks:
      - microservices
 
  # ---- 订单服务 ----
  order-service:
    build:
      context: ./services/order-service
      dockerfile: Dockerfile.dev
    ports:
      - "3001:3001"
    environment:
      - NODE_ENV=development
      - DATABASE_URL=postgresql://postgres:postgres@order-db:5432/orders
      - RABBITMQ_URL=amqp://rabbitmq:5672
    depends_on:
      order-db:
        condition: service_healthy
      rabbitmq:
        condition: service_healthy
    networks:
      - microservices
 
  # ---- 库存服务 ----
  inventory-service:
    build:
      context: ./services/inventory-service
      dockerfile: Dockerfile.dev
    ports:
      - "3002:3002"
    environment:
      - NODE_ENV=development
      - DATABASE_URL=postgresql://postgres:postgres@inventory-db:5432/inventory
      - RABBITMQ_URL=amqp://rabbitmq:5672
    depends_on:
      inventory-db:
        condition: service_healthy
      rabbitmq:
        condition: service_healthy
    networks:
      - microservices
 
  # ---- 用户服务 ----
  user-service:
    build:
      context: ./services/user-service
      dockerfile: Dockerfile.dev
    ports:
      - "3003:3003"
    environment:
      - NODE_ENV=development
      - DATABASE_URL=postgresql://postgres:postgres@user-db:5432/users
      - REDIS_URL=redis://redis:6379
    depends_on:
      user-db:
        condition: service_healthy
      redis:
        condition: service_healthy
    networks:
      - microservices
 
  # ---- 数据库（每个服务独立数据库） ----
  order-db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: orders
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    volumes:
      - order-db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5
    networks:
      - microservices
 
  inventory-db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: inventory
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    volumes:
      - inventory-db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5
    networks:
      - microservices
 
  user-db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: users
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    volumes:
      - user-db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5
    networks:
      - microservices
 
  # ---- 基础设施 ----
  rabbitmq:
    image: rabbitmq:3.13-management-alpine
    ports:
      - "5672:5672"
      - "15672:15672"   # 管理 UI
    healthcheck:
      test: ["CMD", "rabbitmq-diagnostics", "check_running"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - microservices
 
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 5s
      retries: 5
    networks:
      - microservices
 
volumes:
  order-db-data:
  inventory-db-data:
  user-db-data:
 
networks:
  microservices:
    driver: bridge

你是一位 Kubernetes 运维专家。请为以下微服务生成生产级 K8s 部署配置。

## 服务信息
- 服务名称：[服务名]
- 容器镜像：[镜像地址:标签]
- 端口：[HTTP 端口] / [gRPC 端口（如有）]
- 健康检查端点：[例如 /health]
- 就绪检查端点：[例如 /ready]

## 资源需求
- CPU 请求/限制：[例如 100m / 500m]
- 内存请求/限制：[例如 128Mi / 512Mi]
- 副本数：[最小/最大]

## 要求
1. Deployment（包含滚动更新策略）
2. Service（ClusterIP + 可选 LoadBalancer）
3. HPA（水平自动扩缩容）
4. ConfigMap（非敏感配置）
5. Secret（敏感配置，使用 External Secrets Operator）
6. NetworkPolicy（限制服务间通信）
7. PodDisruptionBudget（保证可用性）
8. ServiceAccount（最小权限）

## 安全要求
- Pod 以非 root 用户运行
- 只读根文件系统
- 禁止特权容器
- 限制 Linux capabilities

# ============================================
# k8s/order-service/deployment.yaml
# 订单服务 Kubernetes 部署配置
# ============================================
 
apiVersion: apps/v1
kind: Deployment
metadata:
  name: order-service
  namespace: production
  labels:
    app: order-service
    version: v1
spec:
  replicas: 3
  selector:
    matchLabels:
      app: order-service
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1          # 滚动更新时最多多 1 个 Pod
      maxUnavailable: 0    # 滚动更新时不允许不可用
  template:
    metadata:
      labels:
        app: order-service
        version: v1
      annotations:
        prometheus.io/scrape: "true"
        prometheus.io/port: "3001"
        prometheus.io/path: "/metrics"
    spec:
      serviceAccountName: order-service
      # 安全上下文
      securityContext:
        runAsNonRoot: true
        runAsUser: 1001
        runAsGroup: 1001
        fsGroup: 1001
      containers:
        - name: order-service
          image: myregistry/order-service:v1.2.3
          ports:
            - name: http
              containerPort: 3001
              protocol: TCP
          # 环境变量
          env:
            - name: NODE_ENV
              value: "production"
            - name: PORT
              value: "3001"
            - name: DATABASE_URL
              valueFrom:
                secretKeyRef:
                  name: order-service-secrets
                  key: database-url
            - name: RABBITMQ_URL
              valueFrom:
                secretKeyRef:
                  name: order-service-secrets
                  key: rabbitmq-url
          # 资源限制
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              cpu: 500m
              memory: 512Mi
          # 存活探针
          livenessProbe:
            httpGet:
              path: /health
              port: http
            initialDelaySeconds: 15
            periodSeconds: 20
            timeoutSeconds: 5
            failureThreshold: 3
          # 就绪探针
          readinessProbe:
            httpGet:
              path: /ready
              port: http
            initialDelaySeconds: 5
            periodSeconds: 10
            timeoutSeconds: 3
            failureThreshold: 3
          # 启动探针（慢启动保护）
          startupProbe:
            httpGet:
              path: /health
              port: http
            initialDelaySeconds: 5
            periodSeconds: 5
            failureThreshold: 30
          # 容器安全上下文
          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
            capabilities:
              drop:
                - ALL
          # 临时目录（只读根文件系统需要）
          volumeMounts:
            - name: tmp
              mountPath: /tmp
      volumes:
        - name: tmp
          emptyDir: {}
      # Pod 反亲和性（分散到不同节点）
      affinity:
        podAntiAffinity:
          preferredDuringSchedulingIgnoredDuringExecution:
            - weight: 100
              podAffinityTerm:
                labelSelector:
                  matchExpressions:
                    - key: app
                      operator: In
                      values:
                        - order-service
                topologyKey: kubernetes.io/hostname
 
---
# Service
apiVersion: v1
kind: Service
metadata:
  name: order-service
  namespace: production
spec:
  selector:
    app: order-service
  ports:
    - name: http
      port: 80
      targetPort: http
      protocol: TCP
  type: ClusterIP
 
---
# HPA（水平自动扩缩容）
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: order-service
  namespace: production
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: order-service
  minReplicas: 3
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70
    - type: Resource
      resource:
        name: memory
        target:
          type: Utilization
          averageUtilization: 80
  behavior:
    scaleUp:
      stabilizationWindowSeconds: 60
      policies:
        - type: Pods
          value: 2
          periodSeconds: 60
    scaleDown:
      stabilizationWindowSeconds: 300
      policies:
        - type: Pods
          value: 1
          periodSeconds: 120
 
---
# PodDisruptionBudget（保证可用性）
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: order-service
  namespace: production
spec:
  minAvailable: 2
  selector:
    matchLabels:
      app: order-service
 
---
# NetworkPolicy（限制网络访问）
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: order-service
  namespace: production
spec:
  podSelector:
    matchLabels:
      app: order-service
  policyTypes:
    - Ingress
    - Egress
  ingress:
    # 只允许 API 网关访问
    - from:
        - podSelector:
            matchLabels:
              app: api-gateway
      ports:
        - protocol: TCP
          port: 3001
  egress:
    # 允许访问数据库
    - to:
        - podSelector:
            matchLabels:
              app: order-db
      ports:
        - protocol: TCP
          port: 5432
    # 允许访问 RabbitMQ
    - to:
        - podSelector:
            matchLabels:
              app: rabbitmq
      ports:
        - protocol: TCP
          port: 5672
    # 允许 DNS 查询
    - to: []
      ports:
        - protocol: UDP
          port: 53
        - protocol: TCP
          port: 53

API 网关架构：

┌─────────────────────────────────────────────────────────────┐
│                      客户端                                  │
│  (Web / Mobile / 第三方)                                     │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                    API 网关                                   │
│                                                             │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐      │
│  │ 认证/授权 │ │ 速率限制  │ │ 请求路由  │ │ 负载均衡  │      │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘      │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐      │
│  │ 请求转换  │ │ 响应缓存  │ │ 断路器   │ │ 日志/监控  │      │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘      │
│  ┌──────────┐ ┌──────────┐                                  │
│  │ CORS     │ │ API 版本  │                                  │
│  └──────────┘ └──────────┘                                  │
└──────┬──────────────┬──────────────┬────────────────────────┘
       │              │              │
       ▼              ▼              ▼
┌──────────┐  ┌──────────┐  ┌──────────┐
│ 用户服务  │  │ 订单服务  │  │ 库存服务  │
│ :3001    │  │ :3002    │  │ :3003    │
└──────────┘  └──────────┘  └──────────┘

你是一位 API 网关配置专家。请为以下微服务架构生成 API 网关配置。

## 微服务列表
[列出所有微服务及其端点]

## 网关选型
- 网关：[Kong / Traefik / APISIX / Nginx]
- 部署方式：[Docker / Kubernetes / 托管服务]

## 路由规则
[描述 URL 路径到服务的映射关系]

## 要求
1. 路由配置（路径前缀匹配 + 服务转发）
2. 认证中间件（JWT 验证，白名单路径）
3. 速率限制（全局 + 每用户）
4. CORS 配置
5. 请求/响应日志
6. 健康检查端点
7. API 版本管理（/v1/, /v2/）
8. 超时配置（连接超时 + 读取超时）
9. 断路器配置（失败阈值 + 恢复时间）
10. SSL/TLS 终止

## 安全要求
- 隐藏后端服务的内部端口和路径
- 移除敏感响应头（X-Powered-By 等）
- 请求大小限制
- IP 白名单/黑名单（如需要）

# ============================================
# traefik/docker-compose.yml
# Traefik API 网关配置（Docker 环境）
# ============================================
 
version: '3.8'
 
services:
  traefik:
    image: traefik:v3.2
    command:
      # API 和 Dashboard
      - "--api.dashboard=true"
      - "--api.insecure=false"
      # Docker Provider
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--providers.docker.network=microservices"
      # 入口点
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      # HTTP → HTTPS 重定向
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      # Let's Encrypt 自动证书
      - "--certificatesresolvers.letsencrypt.acme.httpchallenge=true"
      - "--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web"
      - "--certificatesresolvers.letsencrypt.acme.email=admin@yourdomain.com"
      - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
      # 访问日志
      - "--accesslog=true"
      - "--accesslog.format=json"
      # Prometheus 指标
      - "--metrics.prometheus=true"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - letsencrypt:/letsencrypt
    networks:
      - microservices
    labels:
      # Dashboard 路由
      - "traefik.enable=true"
      - "traefik.http.routers.dashboard.rule=Host(`traefik.yourdomain.com`)"
      - "traefik.http.routers.dashboard.service=api@internal"
      - "traefik.http.routers.dashboard.tls.certresolver=letsencrypt"
      # Dashboard 认证
      - "traefik.http.routers.dashboard.middlewares=dashboard-auth"
      - "traefik.http.middlewares.dashboard-auth.basicauth.users=admin:$$apr1$$..."
 
  # ---- 微服务路由配置（通过 Docker Labels） ----
 
  order-service:
    image: myregistry/order-service:latest
    networks:
      - microservices
    labels:
      - "traefik.enable=true"
      # 路由规则
      - "traefik.http.routers.orders.rule=Host(`api.yourdomain.com`) && PathPrefix(`/api/v1/orders`)"
      - "traefik.http.routers.orders.tls.certresolver=letsencrypt"
      # 中间件链
      - "traefik.http.routers.orders.middlewares=rate-limit,cors,strip-prefix"
      # 服务端口
      - "traefik.http.services.orders.loadbalancer.server.port=3001"
      # 健康检查
      - "traefik.http.services.orders.loadbalancer.healthcheck.path=/health"
      - "traefik.http.services.orders.loadbalancer.healthcheck.interval=10s"
 
  inventory-service:
    image: myregistry/inventory-service:latest
    networks:
      - microservices
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.inventory.rule=Host(`api.yourdomain.com`) && PathPrefix(`/api/v1/inventory`)"
      - "traefik.http.routers.inventory.tls.certresolver=letsencrypt"
      - "traefik.http.routers.inventory.middlewares=rate-limit,cors"
      - "traefik.http.services.inventory.loadbalancer.server.port=3002"
 
  user-service:
    image: myregistry/user-service:latest
    networks:
      - microservices
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.users.rule=Host(`api.yourdomain.com`) && PathPrefix(`/api/v1/users`)"
      - "traefik.http.routers.users.tls.certresolver=letsencrypt"
      - "traefik.http.routers.users.middlewares=rate-limit,cors"
      - "traefik.http.services.users.loadbalancer.server.port=3003"
 
# ---- 全局中间件定义 ----
# （通过 Traefik 动态配置文件或 Docker Labels）
 
# 速率限制中间件
# traefik.http.middlewares.rate-limit.ratelimit.average=100
# traefik.http.middlewares.rate-limit.ratelimit.burst=50
# traefik.http.middlewares.rate-limit.ratelimit.period=1s
 
# CORS 中间件
# traefik.http.middlewares.cors.headers.accesscontrolallowmethods=GET,POST,PUT,DELETE,OPTIONS
# traefik.http.middlewares.cors.headers.accesscontrolalloworiginlist=https://yourdomain.com
# traefik.http.middlewares.cors.headers.accesscontrolmaxage=86400
 
volumes:
  letsencrypt:
 
networks:
  microservices:
    external: true

断路器状态机：

┌──────────┐     失败次数 ≥ 阈值     ┌──────────┐
│          │ ──────────────────────→ │          │
│  CLOSED  │                         │   OPEN   │
│ （正常）  │ ←────────────────────── │ （熔断）  │
│          │     半开状态测试成功      │          │
└──────────┘                         └────┬─────┘
     ↑                                    │
     │          超过恢复时间               │
     │         ┌──────────┐               │
     └──────── │HALF-OPEN │ ←─────────────┘
    测试成功    │（半开）   │
               └──────────┘
                    │
                    │ 测试失败
                    └──────→ 回到 OPEN

状态说明：
• CLOSED（关闭）：正常状态，请求正常转发
  - 记录失败次数
  - 失败次数达到阈值 → 切换到 OPEN

• OPEN（打开/熔断）：拒绝所有请求，快速失败
  - 返回降级响应（缓存数据/默认值/错误提示）
  - 等待恢复时间

• HALF-OPEN（半开）：允许少量请求测试
  - 如果测试请求成功 → 切换到 CLOSED
  - 如果测试请求失败 → 切换回 OPEN

// ============================================
// resilience/circuit-breaker.ts
// 通用断路器实现
// ============================================
 
enum CircuitState {
  CLOSED = 'CLOSED',
  OPEN = 'OPEN',
  HALF_OPEN = 'HALF_OPEN',
}
 
interface CircuitBreakerConfig {
  failureThreshold: number;     // 失败阈值（触发熔断）
  successThreshold: number;     // 成功阈值（恢复正常）
  timeout: number;              // 熔断恢复时间（ms）
  monitorInterval: number;      // 监控窗口（ms）
}
 
interface CircuitBreakerMetrics {
  state: CircuitState;
  failures: number;
  successes: number;
  lastFailureTime: number;
  totalRequests: number;
  totalFailures: number;
}
 
class CircuitBreaker {
  private state: CircuitState = CircuitState.CLOSED;
  private failures = 0;
  private successes = 0;
  private lastFailureTime = 0;
  private totalRequests = 0;
  private totalFailures = 0;
 
  constructor(
    private readonly name: string,
    private readonly config: CircuitBreakerConfig,
  ) {}
 
  /**
   * 通过断路器执行操作
   * @param action 要执行的异步操作
   * @param fallback 降级函数（断路器打开时调用）
   */
  async execute<T>(
    action: () => Promise<T>,
    fallback?: () => Promise<T>,
  ): Promise<T> {
    this.totalRequests++;
 
    // 检查断路器状态
    if (this.state === CircuitState.OPEN) {
      // 检查是否可以进入半开状态
      if (Date.now() - this.lastFailureTime >= this.config.timeout) {
        this.state = CircuitState.HALF_OPEN;
        this.successes = 0;
      } else {
        // 断路器打开：执行降级
        if (fallback) {
          return fallback();
        }
        throw new CircuitBreakerOpenError(this.name);
      }
    }
 
    try {
      const result = await action();
      this.onSuccess();
      return result;
    } catch (error) {
      this.onFailure();
      if (this.state === CircuitState.OPEN && fallback) {
        return fallback();
      }
      throw error;
    }
  }
 
  private onSuccess(): void {
    if (this.state === CircuitState.HALF_OPEN) {
      this.successes++;
      if (this.successes >= this.config.successThreshold) {
        // 恢复正常
        this.state = CircuitState.CLOSED;
        this.failures = 0;
        this.successes = 0;
        console.log(`[CircuitBreaker:${this.name}] 恢复正常 (CLOSED)`);
      }
    } else {
      this.failures = 0; // 重置连续失败计数
    }
  }
 
  private onFailure(): void {
    this.failures++;
    this.totalFailures++;
    this.lastFailureTime = Date.now();
 
    if (this.state === CircuitState.HALF_OPEN) {
      // 半开状态下失败：回到打开状态
      this.state = CircuitState.OPEN;
      console.log(`[CircuitBreaker:${this.name}] 半开测试失败，重新熔断 (OPEN)`);
    } else if (this.failures >= this.config.failureThreshold) {
      // 达到失败阈值：打开断路器
      this.state = CircuitState.OPEN;
      console.log(`[CircuitBreaker:${this.name}] 触发熔断 (OPEN)，连续失败 ${this.failures} 次`);
    }
  }
 
  getMetrics(): CircuitBreakerMetrics {
    return {
      state: this.state,
      failures: this.failures,
      successes: this.successes,
      lastFailureTime: this.lastFailureTime,
      totalRequests: this.totalRequests,
      totalFailures: this.totalFailures,
    };
  }
}
 
class CircuitBreakerOpenError extends Error {
  constructor(serviceName: string) {
    super(`断路器已打开：${serviceName} 服务暂时不可用`);
    this.name = 'CircuitBreakerOpenError';
  }
}

// ============================================
// resilience/fallback-strategies.ts
// 常见降级策略
// ============================================
 
// 策略 1：缓存降级（返回缓存的旧数据）
class CacheFallback<T> {
  private cache: Map<string, { data: T; timestamp: number }> = new Map();
 
  constructor(private readonly ttl: number = 300_000) {} // 默认 5 分钟
 
  set(key: string, data: T): void {
    this.cache.set(key, { data, timestamp: Date.now() });
  }
 
  get(key: string): T | null {
    const entry = this.cache.get(key);
    if (!entry) return null;
    if (Date.now() - entry.timestamp > this.ttl) {
      this.cache.delete(key);
      return null;
    }
    return entry.data;
  }
}
 
// 策略 2：默认值降级
function defaultFallback<T>(defaultValue: T): () => Promise<T> {
  return async () => defaultValue;
}
 
// 策略 3：部分降级（返回部分数据）
async function partialFallback(
  services: Array<{ name: string; call: () => Promise<any> }>,
): Promise<Record<string, any>> {
  const results: Record<string, any> = {};
 
  await Promise.allSettled(
    services.map(async (service) => {
      try {
        results[service.name] = await service.call();
      } catch {
        results[service.name] = null; // 失败的服务返回 null
      }
    }),
  );
 
  return results;
}
 
// ---- 使用示例 ----
 
const inventoryBreaker = new CircuitBreaker('inventory-service', {
  failureThreshold: 5,      // 连续 5 次失败触发熔断
  successThreshold: 3,       // 连续 3 次成功恢复
  timeout: 30_000,           // 30 秒后尝试恢复
  monitorInterval: 60_000,   // 60 秒监控窗口
});
 
const inventoryCache = new CacheFallback<InventoryCheckResponse>();
 
async function checkInventoryWithResilience(
  productId: string,
  quantity: number,
  traceId: string,
): Promise<InventoryCheckResponse> {
  return inventoryBreaker.execute(
    // 正常调用
    async () => {
      const result = await inventoryClient.checkAvailability(
        { productId, quantity },
        traceId,
      );
      // 成功时更新缓存
      inventoryCache.set(productId, result);
      return result;
    },
    // 降级策略：返回缓存数据
    async () => {
      const cached = inventoryCache.get(productId);
      if (cached) {
        console.warn(`[Fallback] 使用缓存的库存数据: ${productId}`);
        return { ...cached, _fromCache: true };
      }
      // 缓存也没有：返回保守的默认值
      console.warn(`[Fallback] 无缓存，返回默认值: ${productId}`);
      return {
        available: false,
        currentStock: 0,
        _fromCache: true,
        _fallback: true,
      };
    },
  );
}