API 连接器构建器¶

当需要添加仓库原生的集成表面时使用。它不是通用 HTTP 客户端。

重点是匹配宿主仓库的模式：

• 连接器布局
• 配置模式
• 认证模型
• 错误处理
• 测试风格
• 注册/发现接线

何时使用¶

• “为这个项目构建 Jira 连接器”
• “按照现有模式添加 Slack 提供者”
• “为这个 API 创建新的集成”
• “构建与仓库连接器风格一致的插件”

护栏¶

• 如果仓库已有集成架构，不要发明新的集成架构。
• 不要只从供应商文档开始。请从仓库内现有连接器开始。
• 如果仓库期望注册表接线、测试和文档，不要只停留在传输代码。
• 如果仓库有新的当前模式，不要盲目照搬旧连接器。

工作流¶

1. 学习内部风格¶

检查至少两个现有连接器/提供者，并映射：

• 文件布局
• 抽象边界
• 配置模型
• 重试/分页约定
• 注册表钩子
• 测试夹具和命名

2. 确定目标集成¶

只定义仓库实际需要的表面：

• 认证流程
• 关键实体
• 核心读取/写入操作
• 分页和速率限制
• Webhook 或轮询模型

3. 以仓库原生层构建¶

常见切片：

• 配置/模式
• 客户端/传输
• 映射层
• 连接器/提供者入口点
• 注册
• 测试

4. 对照源模式验证¶

新连接器应该看起来像是代码库中显而易见的，而不是从另一个生态系统导入的。

参考结构¶

提供者风格¶

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

连接器风格¶

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

TypeScript 插件风格¶

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

质量检查清单¶

• [ ] 与现有仓库内集成模式一致
• [ ] 存在配置验证
• [ ] 认证和错误处理是明确的
• [ ] 分页/重试行为遵循仓库规范
• [ ] 注册表/发现接线已完成
• [ ] 测试反映宿主仓库的风格
• [ ] 如果仓库期望，则更新文档/示例

相关技能¶

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