Giới thiệu

Bạn đã viết xong tài liệu OpenAPI cho API của mình. Nó đẹp, được tài liệu hóa tốt và mô tả chính xác API của bạn. Nhưng giờ đây, bạn cần triển khai nó lên AWS API Gateway, và điều đó có nghĩa là bạn phải viết Terraform. Điều này đã lặp đi lặp lại nhiều lần trong tháng này.

Vấn đề

Việc này nghe có vẻ quen thuộc? Bạn đang lặp lại thông tin mà đã tồn tại trong tài liệu OpenAPI của mình. Nếu tài liệu API có thể là định nghĩa cơ sở hạ tầng của bạn thì sao? Sự lặp lại này đã khiến tôi cảm thấy phiền phức đủ để xây dựng một công cụ cho nó. Thay vì duy trì hai nguồn thông tin khác nhau (tài liệu OpenAPI + Terraform), bạn có thể để tài liệu API tự động sinh ra hạ tầng.

Cách thức hoạt động

Công cụ (Striche Gateway) hoạt động theo một quy trình đơn giản:

• OpenAPI Spec → Mô hình chuẩn → Mẫu nền tảng → Terraform → Hạ tầng đã triển khai

1. Phân tích tài liệu Spec

Công cụ sẽ phân tích cấu trúc API, các đường dẫn, phương thức và các mở rộng tùy chỉnh:

const spec = await parseOpenAPI('payment-api.yaml');
const service = spec.info['x-service'] || 'default';
const routes = extractRoutes(spec.paths);
const rateLimits = extractRateLimits(spec.paths);

2. Tạo hạ tầng

Sử dụng mẫu Handlebars để tạo ra Terraform sạch sẽ:

module "{{service}}_service" {
  source = "./modules/service"

  service_name = "{{service}}"
  routes = [
    {{#each routes}}
    {
      path = "{{path}}"
      method = "{{method}}"
      {{#if rateLimit}}
      rate_limit = {{rateLimit.requests}}
      burst_limit = {{rateLimit.burst}}
      {{/if}}
    }{{#unless @last}},{{/unless}}
    {{/each}}
  ]
}

3. Triển khai

Quy trình Terraform tiêu chuẩn - không có gì kỳ diệu, chỉ là tự động hóa:

tf init
tf plan
tf apply

Mô hình Gateway thống nhất

Phần thú vị không chỉ là tạo các cấu hình API Gateway cơ bản. Nó còn giải quyết vấn đề "nhiều microservices, một gateway". Thay vì triển khai riêng biệt các gateway cho mỗi dịch vụ:

./striche.sh deploy -s auth-api.yaml,payments-api.yaml,orders-api.yaml -p aws

Các tiện ích mở rộng OpenAPI: Gợi ý hạ tầng

Sự hiểu biết chính là sử dụng cơ chế mở rộng của OpenAPI để nhúng cấu hình hạ tầng:

paths:
  /login:
    post:
      x-rate-limit:
        requests: 10    # Cho phép 10 lần thử đăng nhập
        period: 60      # trong một phút
        burst: 15       # với bảo vệ burst
      x-service: auth   # Đường dẫn đến backend auth

Từ tài liệu đến Terraform

Các mở rộng này sẽ được dịch trực tiếp thành các tài nguyên Terraform:

resource "aws_apigatewayv2_route" "auth_login" {
  api_id    = aws_apigatewayv2_api.main.id
  route_key = "POST /auth/login"

  throttle_settings {
    rate_limit  = 10
    burst_limit = 15
  }
}

Lợi ích thực tế

Sau khi áp dụng phương pháp này cho nhiều lần triển khai microservices:

• Tiết kiệm thời gian: Những gì trước đây mất 30-45 phút viết Terraform giờ chỉ còn 2 phút.
• Tính nhất quán: Mỗi API Gateway đều theo cùng một mẫu và thực hành tốt.
• Nguồn thông tin duy nhất: Tài liệu API và cấu hình hạ tầng sống cùng nhau.
• Cập nhật dễ dàng: Thay đổi tài liệu, triển khai lại, hạ tầng được cập nhật tự động.

So sánh Terraform sinh ra và viết tay

Đầu ra là Terraform chuẩn mà bạn có thể đã viết bằng tay:

out/
├── main.tf              # Cấu hình gốc sạch sẽ, dễ đọc
├── variables.tf         # Tham số đầu vào
├── terraform.tfvars     # Giá trị cụ thể cho dịch vụ
├── outputs.tf           # URL và ID của API Gateway
└── modules/
    └── service/         # Mô-đun dịch vụ tái sử dụng
        ├── main.tf
        ├── variables.tf
        └── outputs.tf

Khi nào nên áp dụng

Phương pháp này có hiệu quả khi:

• Bạn có nhiều API với các mẫu hạ tầng tương tự.
• Nhóm của bạn đã duy trì tài liệu OpenAPI.
• Bạn muốn tính nhất quán trong các lần triển khai dịch vụ.
• Các quy tắc giới hạn tỷ lệ và định tuyến thường xuyên thay đổi.

Thử nghiệm ngay

Công cụ này là mã nguồn mở và có sẵn trên GitHub:

git clone https://github.com/striche-AI/striche-gateway
cd striche-gateway
npm install

Tương lai

Điều này thực sự là về việc thu hẹp khoảng cách giữa thiết kế API và triển khai hạ tầng. Tài liệu OpenAPI của bạn đã mô tả hành vi của API - tại sao không để nó mô tả cả hạ tầng? Chúng ta đang tiến tới một thế giới mà hạ tầng trở nên rõ ràng hơn và ít thủ công hơn. Việc coi tài liệu API như là định nghĩa hạ tầng cảm thấy như một sự tiến hóa tự nhiên.