Back to Details

api-connector-builder

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

API Connector Builder

API 连接器构建器

Use this when the job is to add a repo-native integration surface, not just a generic HTTP client.
The point is to match the host repository's pattern:
  • connector layout
  • config schema
  • auth model
  • error handling
  • test style
  • registration/discovery wiring
当任务是添加仓库原生的集成接口，而非仅实现通用HTTP客户端时使用本指南。
核心要点是匹配宿主仓库的模式：
  • 连接器布局
  • 配置Schema
  • 认证模型
  • 错误处理
  • 测试风格
  • 注册/发现绑定逻辑

When to Use

适用场景

  • "Build a Jira connector for this project"
  • "Add a Slack provider following the existing pattern"
  • "Create a new integration for this API"
  • "Build a plugin that matches the repo's connector style"
  • "为该项目构建Jira连接器"
  • "遵循现有模式添加Slack provider"
  • "为该API创建新集成"
  • "构建符合仓库连接器风格的插件"

Guardrails

注意事项

  • do not invent a new integration architecture when the repo already has one
  • do not start from vendor docs alone; start from existing in-repo connectors first
  • do not stop at transport code if the repo expects registry wiring, tests, and docs
  • do not cargo-cult old connectors if the repo has a newer current pattern
  • 当仓库已有集成架构时，不要重新设计新的集成架构
  • 不要仅参考厂商文档开发，要先从仓库内现有连接器入手
  • 如果仓库要求包含注册绑定逻辑、测试和文档，不要只完成传输层代码就结束
  • 如果仓库已有更新的现行模式，不要盲目照搬旧连接器的代码

Workflow

工作流程

1. Learn the house style

1. 学习项目内部规范

Inspect at least 2 existing connectors/providers and map:
  • file layout
  • abstraction boundaries
  • config model
  • retry / pagination conventions
  • registry hooks
  • test fixtures and naming
至少调研2个现有连接器/provider，梳理以下内容：
  • 文件结构
  • 抽象边界
  • 配置模型
  • 重试/分页约定
  • 注册钩子
  • 测试用例和命名规范

2. Narrow the target integration

2. 明确目标集成范围

Define only the surface the repo actually needs:
  • auth flow
  • key entities
  • core read/write operations
  • pagination and rate limits
  • webhook or polling model
仅定义仓库实际需要的接口：
  • 认证流程
  • 核心实体
  • 核心读写操作
  • 分页和速率限制
  • Webhook或轮询模式

3. Build in repo-native layers

3. 按仓库原生分层实现

Typical slices:
  • config/schema
  • client/transport
  • mapping layer
  • connector/provider entrypoint
  • registration
  • tests
典型分层如下：
  • 配置/Schema
  • 客户端/传输层
  • 映射层
  • 连接器/provider入口
  • 注册逻辑
  • 测试

4. Validate against the source pattern

4. 对照原有模式验证

The new connector should look obvious in the codebase, not imported from a different ecosystem.
新连接器应当和代码库风格高度统一，看起来不像是从其他生态导入的。

Reference Shapes

参考结构

Provider-style

Provider风格

text
providers/
  existing_provider/
    __init__.py
    provider.py
    config.py
text
providers/
  existing_provider/
    __init__.py
    provider.py
    config.py

Connector-style

连接器风格

text
integrations/
  existing/
    client.py
    models.py
    connector.py
text
integrations/
  existing/
    client.py
    models.py
    connector.py

TypeScript plugin-style

TypeScript插件风格

text
src/integrations/
  existing/
    index.ts
    client.ts
    types.ts
    test.ts
text
src/integrations/
  existing/
    index.ts
    client.ts
    types.ts
    test.ts

Quality Checklist

质量检查清单

  • matches an existing in-repo integration pattern
  • config validation exists
  • auth and error handling are explicit
  • pagination/retry behavior follows repo norms
  • registry/discovery wiring is complete
  • tests mirror the host repo's style
  • docs/examples are updated if expected by the repo
  • 符合仓库现有集成模式
  • 已实现配置校验
  • 认证和错误处理逻辑清晰
  • 分页/重试行为符合仓库规范
  • 注册/发现绑定逻辑完整
  • 测试符合宿主仓库风格
  • 如仓库有要求，已更新文档/示例

Related Skills

相关技能

  • backend-patterns
  • mcp-server-patterns
  • github-ops
  • backend-patterns
  • mcp-server-patterns
  • github-ops