api/README.md

@go/api

@go/api 是一个极致精简、接口驱动、AI 友好的 API 调用引擎。它旨在消除对接第三方服务（如腾讯云、阿里云、OpenAI 等）时的繁琐 SDK 依赖和硬编码摩擦。

🎯 设计哲学

• 数据驱动 (Data-Driven)：一切皆数据，通过强类型 Action 结构体描述请求。
• 无状态 (Stateless)：核心库不绑定任何具体的云服务实现，仅提供标准协议支持。
• AI 友好 (AI-First)：极其简单的结构体定义，消除了幻觉，让 AI 能够精准生成调用代码。
• 非破坏性注入：支持从配置自动回填缺失参数（如 AppId, SecretId），但不覆盖显式设置的值。

📦 安装

go get apigo.cc/go/api

💡 核心流程

1. 定义 Action：实现 Action 接口（及可选的 SignerAction, ConfigurableAction 等）。
2. 配置授权：在 api.yml 或环境变量中配置密钥。
3. 发起调用：使用 api.Call[Response](&action)。

🛠 接口说明

• Action：核心标识接口，定义动作名称（如 tencent.sms.smsPackagesStatistics）。
• SignerAction：指定签名算法名称（如 tc3）。
• ConfigurableAction：提供硬编码的默认参数或元数据。
• URLAction / MethodAction：动态指定 Endpoint 和 HTTP 方法。
• ValidatableAction：业务参数自校验。

🔒 安全性

• 内置解密：支持自动识别并解密配置中的 AES 加密内容。
• 并发安全：配置树操作受 sync.RWMutex 保护。

🧪 示例

type MySmsAction struct {
    Limit int
    AppId string // 自动从配置注入
}
func (MySmsAction) ActionName() string { return "tencent.sms.smsPackagesStatistics" }
func (MySmsAction) SignerName() string { return "tc3" }

resp, err := api.Call[MyResponse](&MySmsAction{Limit: 10})

---

更多详情请参阅 TEST.md 和 CHANGELOG.md。