gaore-common-sdk-go/CLAUDE.md

CLAUDE.md

本文件为 Claude Code (claude.ai/code) 在此仓库中工作时提供指引。

常用命令

# 运行某个 service 的全部测试
go test ./services/apk/...

# 运行单个测试函数
go test ./services/apk/... -run TestClient_GetUserInfo -v

# 编译检查
go build ./...

整体架构

分两层：

• sdk/：核心框架，处理签名、HTTP 请求、响应解析，不含业务逻辑
• services/<name>/：各业务服务封装，每个包是一个独立 SDK client

sdk/ 核心流程

调用方 → Client.DoAction(req, resp)
        → auth.Sign(req, signer)      # 根据 credential 类型签名
        → req.BuildUrl()              # RpcRequest 拼接域名+路径+query
        → HTTP 请求
        → responses.Unmarshal(resp)   # JSON 反序列化

• sdk/auth/credentials/：三种凭证类型（AccessKey、StsToken、AliAppcode）
• sdk/auth/signers/：对应签名器实现
• sdk/requests/：RpcRequest（主流）和 RoaRequest 两种请求风格；字段通过 struct tag position:"Body|Query|Header" 和 field:"xxx" 声明参数位置
• sdk/config.go：Config 结构体，字段用 default:"..." tag 自动初始化

services/ 统一模式

每个服务包含：

文件	职责
client.go	定义 Client（内嵌 sdk.Client）、HOST、VERSION 常量，以及所有对外方法
xxx_action.go	每个接口一个文件，包含 Request/Response 结构体和两个工厂函数

添加新接口的标准步骤

1. 新建 services/<name>/new_action.go：

package <name>

import (
    "golib.gaore.com/GaoreGo/gaore-common-sdk-go/sdk/requests"
    "golib.gaore.com/GaoreGo/gaore-common-sdk-go/sdk/responses"
)

type NewActionRequest struct {
    *requests.RpcRequest
    Field1 string `position:"Body" field:"field1" default:""`
    Field2 int64  `position:"Body" field:"field2"`
}

type NewActionResponse struct {
    *responses.BaseResponse
    Code int    `json:"code"`
    Msg  string `json:"msg"`
    Data struct {
        // ...
    } `json:"data"`
}

func CreateNewActionRequest() *NewActionRequest {
    req := &NewActionRequest{RpcRequest: &requests.RpcRequest{}}
    req.InitWithApiInfo(HOST, VERSION, "/api/path/here")
    req.Method = requests.POST
    return req
}

func CreateNewActionResponse() *NewActionResponse {
    return &NewActionResponse{BaseResponse: &responses.BaseResponse{}}
}

2. 在 client.go 添加方法：

func (c *Client) NewAction(req *NewActionRequest) (response *NewActionResponse, err error) {
    response = CreateNewActionResponse()
    err = c.DoAction(req, response)
    return
}

HOST 两种写法

// 简单写法（内部服务，hostname 由调用方注入）
var HOST = requests.Host{Default: "service-name"}

// 带环境路由写法（外部服务，各环境域名不同）
var HOST = requests.Host{
    Default: "api.example.com",
    Func: func(env string) string {
        return map[string]string{
            requests.RELEASE: "api.example.com",
            requests.TEST:    "test.api.example.com",
        }[env]
    },
}

环境常量：requests.RELEASE、requests.PRE、requests.TEST

Client 初始化两种模式

// 模式一：无需认证（apk、callback 等内部服务）
func NewClient() *Client {
    client := &Client{}
    client.InitWithAccessKey("", "", "")
    return client
}

// 模式二：需要认证（sso、pay 等）
func NewClient() (*Client, error) {
    client := new(Client)
    err := client.Init()
    return client, err
}