Back to Details

api-integration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

API Integration

API集成

Build robust, type-safe API clients from specs and documentation.
根据规范和文档构建健壮的、类型安全的API客户端。

Key Principles

核心原则

  • Type everything — Runtime-validated types for all requests and responses
  • Fail explicitly — No silent failures; throw typed errors with context
  • Auth is first-class — Handle auth in the client layer, not scattered in calls
  • Retry intelligently — Only idempotent methods, only transient failures, with backoff
  • Isolate the boundary — Transform API shapes at the integration layer, not in app code
  • 全类型覆盖 — 对所有请求和响应做运行时类型校验
  • 显式报错 — 不允许静默失败，抛出携带上下文的带类型错误
  • 鉴权一等公民 — 在客户端层统一处理鉴权逻辑，不要分散在各个调用处
  • 智能重试 — 仅对幂等方法、瞬态错误执行重试，且附带退避策略
  • 边界隔离 — 在集成层转换API数据结构，不要在应用业务代码中处理

When NOT to Use

不适用场景

  • Designing your own APIs — Use 
    api-design
    for building endpoints others will consume
  • Writing API test suites — Use 
    testing-strategy
    for test architecture, contract tests, mocking
  • Building SDKs for your API — Use 
    sdk-development
    for packaging your own API as a client library
  • 设计自研API — 如果你要构建供其他人调用的接口，请使用
    api-design
    相关规范
  • 编写API测试套件 — 测试架构、契约测试、Mock相关内容请参考
    testing-strategy
  • 为你的API构建SDK — 如果你要将自有API打包为客户端库，请使用
    sdk-development
    相关规范

Quick Start Checklist

快速入门检查清单

  1. Obtain API credentials and locate documentation (spec, docs, or examples)
  2. Analyze inputs: extract base URL, auth scheme, endpoints, error formats
  3. Choose architecture: typed wrapper (1-5 endpoints), service class (5-20), or generated client (20+)
  4. Implement types, client, auth handling, and error classification
  5. Add retry logic for transient failures and rate limit handling
  6. Write tests with mocked responses and error scenarios
  1. 获取API凭证并找到对应的文档（规范、说明文档或示例）
  2. 分析输入信息：提取基础URL、鉴权方案、端点列表、错误格式
  3. 选择架构：类型封装（1-5个端点）、服务类（5-20个端点）或生成客户端（20个以上端点）
  4. 实现类型定义、客户端、鉴权处理和错误分类逻辑
  5. 为瞬态错误添加重试逻辑和限流处理
  6. 使用Mock响应和错误场景编写测试用例

References

参考资料

ReferenceDescription
openapi-specs-types.mdParsing OpenAPI specs, type generation strategies
openapi-patterns-codegen.mdCommon patterns, client generation, GraphQL, informal docs
client-base-service-layer.mdBase client, interceptors, service layer pattern
client-request-response-caching.mdRequest config, response parsing, caching, logging
error-classification.mdError type hierarchy, classification, response conversion
error-retry-circuit-breaker.mdRetry with backoff, rate limits, circuit breaker
error-fallback-patterns.mdFallback strategies, Result type, error boundaries, reporting
auth-api-keys-bearer.mdAPI key and bearer token authentication
auth-oauth2.mdOAuth 2.0 authorization code, PKCE, client credentials
auth-jwt-hmac-storage.mdJWT handling, HMAC signatures, secure token storage
testing-mocking-fixtures.mdHTTP mocking (MSW, Nock), test fixtures
testing-unit-integration.mdUnit tests for transformers, integration tests for services
testing-contract-e2e-config.mdContract testing, E2E tests, Jest configuration
参考链接描述
openapi-specs-types.md解析OpenAPI规范、类型生成策略
openapi-patterns-codegen.md通用模式、客户端生成、GraphQL、非正规文档处理
client-base-service-layer.md基础客户端、拦截器、服务层模式
client-request-response-caching.md请求配置、响应解析、缓存、日志
error-classification.md错误类型层级、分类、响应转换
error-retry-circuit-breaker.md带退避的重试、限流、熔断器
error-fallback-patterns.md降级策略、Result类型、错误边界、上报
auth-api-keys-bearer.mdAPI密钥和Bearer令牌身份认证
auth-oauth2.mdOAuth 2.0授权码模式、PKCE、客户端凭证
auth-jwt-hmac-storage.mdJWT处理、HMAC签名、安全令牌存储
testing-mocking-fixtures.mdHTTP Mock（MSW、Nock）、测试固件
testing-unit-integration.md转换器单元测试、服务集成测试
testing-contract-e2e-config.md契约测试、E2E测试、Jest配置