api

README

@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：业务参数自校验。

🔒 安全性 (Ultimate Memory Safety)

• 内置解密：支持自动识别并解密配置中的 AES 加密内容。
• 内存保护：敏感配置解密后以 safe.SafeBuf 形式存储，防止内存 Dump 泄露。

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

🧪 示例

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。

Documentation

Index

• Variables
• func Call[T any](action Action) (*T, error)
• func ExportGoStructs(packageName string) string
• func GetActionConfig(actionName string) (map[string]any, []*safe.SafeBuf)
• func GetBytesOrSafe(v any) ([]byte, func())
• func GetManifest() map[string]any
• func GetStringOrSafe(v any) (string, func())
• func Load(name string) error
• func MergeMap(dst, src map[string]any)
• func RegisterSigner(name string, s Signer)
• func SetEncryptKeys(key, iv []byte)
• type Action
• type ConfigurableAction
• type HttpRequest
  • func (r *HttpRequest) Close()
  • func (r *HttpRequest) GetHeader(key string) string
  • func (r *HttpRequest) SetHeader(key string, values ...any)
• type MethodAction
• type Result
• type Signer
  • func GetSigner(name string) Signer
• type SignerAction
• type URLAction
• type ValidatableAction

Variables

var GlobalConfigs = map[string]any{}

GlobalConfigs 存储整棵配置树

Functions

func Call

func Call[T any](action Action) (*T, error)

Call 是调度引擎的入口

func ExportGoStructs

func ExportGoStructs(packageName string) string

ExportGoStructs 根据全局配置生成 Go 结构体代码

func GetActionConfig

func GetActionConfig(actionName string) (map[string]any, []*safe.SafeBuf)

GetActionConfig 获取某个动作经过层级合并后的完整配置，返回配置图和需要手动关闭的 SafeBuf 列表

func GetBytesOrSafe

func GetBytesOrSafe(v any) ([]byte, func())

GetBytesOrSafe 从配置中安全地获取字节切片。如果是 SafeBuf，则返回明文副本及对应的清理函数

func GetManifest

func GetManifest() map[string]any

GetManifest 返回 API 的描述信息，方便 AI 阅读

func GetStringOrSafe

func GetStringOrSafe(v any) (string, func())

GetStringOrSafe 从配置中安全地获取字符串值。如果是 SafeBuf，则返回明文副本及对应的清理函数

func Load

func Load(name string) error

Load 加载指定的配置文件并合并到 GlobalConfigs

func MergeMap

func MergeMap(dst, src map[string]any)

MergeMap 深度合并两个 map

func RegisterSigner

func RegisterSigner(name string, s Signer)

RegisterSigner 注册全局签名器

func SetEncryptKeys

func SetEncryptKeys(key, iv []byte)

SetEncryptKeys 允许设置自定义的配置加解密密钥

Types

type Action

type Action interface {
	ActionName() string // 例如: "tencent.sms.send"
}

Action 是所有接口的基础标识接口

type ConfigurableAction

type ConfigurableAction interface {
	Config() map[string]any
}

ConfigurableAction 定义可以提供默认硬编码配置的动作

type HttpRequest

type HttpRequest struct {
	Url    string
	Method string

	Payload any
	// contains filtered or unexported fields
}

HttpRequest 内部使用的请求描述结构，供 Signer 使用

func (*HttpRequest) Close

func (r *HttpRequest) Close()

Close 物理覆盖并清除所有关联的敏感缓冲区，确保内存中不再留存明文

func (*HttpRequest) GetHeader

func (r *HttpRequest) GetHeader(key string) string

GetHeader 获取指定 Header 的值

func (*HttpRequest) SetHeader

func (r *HttpRequest) SetHeader(key string, values ...any)

SetHeader 提供无感知的安全 Header 设置功能。支持传入多个参数进行自动拼接。 如果参数中包含 *safe.SafeBuf, *safe.SecretPlaintext 或 []byte (标记为敏感)， 整个生成的 Header 缓冲区都将被注册用于后置物理擦除。 安全的拼接与转换（如 safe.Concat, safe.Base64）建议使用 safe 包提供的返回 *safe.SafeBuf 的方法。

type MethodAction

type MethodAction interface {
	GetMethod() string // 例如: "GET"
}

MethodAction 定义显式指定方法的动作

type Result

type Result struct {
	StatusCode int
	Status     string
	Headers    map[string]string
	Data       any
}

Result 定义 API 调用的标准返回结果

type Signer

type Signer interface {
	Sign(req *HttpRequest, config map[string]any) error
}

Signer 负责为请求附加签名信息

func GetSigner

func GetSigner(name string) Signer

GetSigner 获取签名器

type SignerAction

type SignerAction interface {
	SignerName() string // 例如: "tc3"
}

SignerAction 定义需要签名的动作

type URLAction

type URLAction interface {
	GetURL() string
}

URLAction 定义显式指定 URL 的动作

type ValidatableAction

type ValidatableAction interface {
	Validate() error
}

ValidatableAction 定义支持自我校验的动作