api/README.md

# @go/api

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

## 🎯 设计哲学

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

## 📦 安装

```bash
go get apigo.cc/go/api
```

## 💡 核心流程

1.  **定义 Action**：实现 `Action` 接口（及可选的 `SignerAction`, `ConfigurableAction` 等）。
2.  **配置授权**：在 `api.yml` 或环境变量中配置密钥。
3.  **发起调用**：使用 `api.Call(action, options)`，统一获得 `Result`。

## 🛠 接口说明

*   `Action`：核心标识接口，定义动作名称（如 `tencent.sms.smsPackagesStatistics`）。
*   `SignerAction`：指定签名算法名称（如 `tc3`）。
*   `ConfigurableAction`：提供硬编码的默认参数或元数据。
*   `URLAction` / `MethodAction`：动态指定 Endpoint 和 HTTP 方法。
*   `ValidatableAction`：业务参数自校验。
*   `CallOptions`：提供内部 Token、超时、临时配置覆盖、Logger 与流式回调。
*   `Result`：统一返回 `ok/statusCode/headers/data/code/error`，业务响应保留在 `data`。
*   `RegisterAction` / `RemoveAction`：动态注册和热更新数据驱动的 Action。
*   `RegisterJSSigner` / `RemoveSigner`：管理 JavaScript Signer。
*   `RegisterJSFilter` / `RemoveFilter`：管理可复用的 JavaScript 请求/响应 Filter。

## 🔒 安全性 (Ultimate Memory Safety)

*   **内置解密**：只识别 `**URLBase64(AESGCM)` 配置密文。
*   **内存保护**：敏感配置解密后以 `safe.SafeBuf` 形式存储，防止内存 Dump 泄露。
- **防止字符串泄露**：通过 `unsafe.String` 零拷贝技术，确保敏感 Header（如 Authorization）在调用结束后可被物理擦除，彻底解决 Go 字符串不可变性导致的堆泄露问题。
- **全生命周期闭环**：`api.Call` 结束后自动触发 `httpReq.Close()`，对所有中间缓冲区进行 `ZeroMemory` 随机覆盖。
- **安全辅助函数**：内置 `SetBasicAuth`, `SetBearerAuth` 等工具，强制执行无拼接的内存安全逻辑。

## 🧪 示例

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

result, err := api.Call(&MySmsAction{Limit: 10}, &api.CallOptions{
    Token: "internal-token",
    Config: map[string]any{"path": "/v1/messages"},
})
```

动态 Action 可以在调用时覆盖非敏感配置：

```go
api.RegisterAction("openai", map[string]any{
    "url": "http://127.0.0.1:8001/v1/chat/completions",
    "method": "POST",
    "signer": "none",
    "tokens": []string{"internal-token"},
})

result, err := api.CallBy("openai", payload, &api.CallOptions{
    Token: "internal-token",
    Config: map[string]any{"path": "/v1/embeddings"},
})
```

`tokens` 未配置或为空时无需 Token。`tokens/enabled/test/logging` 与原配置中的密文字段不能通过 `options.config` 覆盖。流式调用使用 `go/http.ManualDo`，`OnHeaders` 与 `OnDone` 接收 lower-camel map，`OnData` 接收原始字节块。

Action 只使用 `filters: ["name"]` 这一种形式。每个 Filter 都会收到前置 `request` 以及后置 `headers/chunk/result/done` 事件，并自行根据 `event` 决定是否处理。流式 Filter 应通过输入/输出的 `state` 保存单次调用状态，不能假设 HTTP chunk 与 SSE 或 JSONL 消息边界一致。JavaScript Filter 的 `chunk` 是 UTF-8 字符串；Go Filter 仍接收原始 `[]byte`，二进制响应不应挂载文本型 JavaScript Filter。

动态 Action 可通过 `extends` 继承另一个 Action；父配置先合并，子配置深度覆盖。继承在每次调用时解析，因此父 Action 热更新会立即作用于子 Action。循环继承或不存在的父 Action 会直接返回错误。

---
更多详情请参阅 [TEST.md](./TEST.md) 和 [CHANGELOG.md](./CHANGELOG.md)。