135 lines
3.5 KiB
Markdown
135 lines
3.5 KiB
Markdown
|
# CLAUDE.md
|
|||
|
|
|
|||
|
|
本文件为 Claude Code (claude.ai/code) 在此仓库中工作时提供指引。
|
|||
|
|
|
|||
|
|
## 常用命令
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 运行某个 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`：**
|
|||
|
|
|
|||
|
|
```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` 添加方法：**
|
|||
|
|
|
|||
|
|
```go
|
|||
|
|
func (c *Client) NewAction(req *NewActionRequest) (response *NewActionResponse, err error) {
|
|||
|
|
response = CreateNewActionResponse()
|
|||
|
|
err = c.DoAction(req, response)
|
|||
|
|
return
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## HOST 两种写法
|
|||
|
|
|
|||
|
|
```go
|
|||
|
|
// 简单写法（内部服务，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 初始化两种模式
|
|||
|
|
|
|||
|
|
```go
|
|||
|
|
// 模式一：无需认证（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
|
|||
|
|
}
|
|||
|
|
```
|