函数 API

通用类型

type JSONValue = json.RawMessage
type JSONSchema = json.RawMessage
type FormPresentationSpec = json.RawMessage
type OpenAPIOperation = json.RawMessage

说明：

JSONValue 仅表示业务 payload 或函数返回值，结构必须由函数 inputSchema / outputSchema 约束。
JSONSchema 仅表示 JSON Schema / OpenAPI Schema。
FormPresentationSpec 表示 JSON Schema 表单的受控展示配置，不能承载页面布局、菜单或任意组件 props。
OpenAPIOperation 只用于契约查看，不用于运行控制台直接生成页面。
json.RawMessage 只是 HTTP 边界上的 JSON 承载类型，服务端必须在保存或执行前完成结构校验。

1. "获取函数列表"

route definition

Url: /api/v1/functions
Method: GET
Request: FunctionsListRequest
Response: FunctionsListResponse

request definition

type FunctionsListRequest struct {
	Page int `form:"page,optional,default=1"`
	PageSize int `form:"pageSize,optional,default=20"`
	GameId string `form:"gameId,optional"`
	Category string `form:"category,optional"`
	Status int `form:"status,optional"`
}

response definition

type FunctionsListResponse struct {
	Items []Function `json:"items"`
	Total int64 `json:"total"`
	Page int `json:"page"`
	Size int `json:"pageSize"`
}

2. "获取函数详情"

route definition

Url: /api/v1/functions/:id
Method: GET
Request: FunctionDetailRequest
Response: FunctionDetailResponse

request definition

type FunctionDetailRequest struct {
	ID string `path:"id"`
}

response definition

type FunctionDetailResponse struct {
	Id string `json:"id"`
	Name string `json:"name"`
	Description string `json:"description"`
	Category string `json:"category"`
	GameId string `json:"gameId"`
	Status int `json:"status"`
	Version string `json:"version"`
	Instances int `json:"instances"`
	CreatedAt string `json:"createdAt"`
	UpdatedAt string `json:"updatedAt"`
	Descriptor FunctionDescriptor `json:"descriptor"`
}

type Function struct {
	Id string `json:"id"`
	Name string `json:"name"`
	Description string `json:"description"`
	Category string `json:"category"`
	GameId string `json:"gameId"`
	Status int `json:"status"`
	Version string `json:"version"`
	Instances int `json:"instances"`
	CreatedAt string `json:"createdAt"`
	UpdatedAt string `json:"updatedAt"`
}

type FunctionDescriptor struct {
	Input JSONSchema `json:"input"`
	Output JSONSchema `json:"output"`
	Schema JSONSchema `json:"schema"`
}

3. "删除函数"

route definition

Url: /api/v1/functions/:id
Method: DELETE
Request: FunctionActionRequest
Response: -

request definition

type FunctionActionRequest struct {
	ID string `path:"id"`
}

response definition

4. "复制函数"

route definition

Url: /api/v1/functions/:id/copy
Method: POST
Request: FunctionCopyRequest
Response: FunctionCopyResponse

request definition

type FunctionCopyRequest struct {
	ID string `path:"id"`
}

response definition

type FunctionCopyResponse struct {
	FunctionId string `json:"functionId"`
	NewId string `json:"newId"`
}

5. "禁用函数"

route definition

Url: /api/v1/functions/:id/disable
Method: POST
Request: FunctionActionRequest
Response: -

request definition

type FunctionActionRequest struct {
	ID string `path:"id"`
}

response definition

6. "启用函数"

route definition

Url: /api/v1/functions/:id/enable
Method: POST
Request: FunctionActionRequest
Response: -

request definition

type FunctionActionRequest struct {
	ID string `path:"id"`
}

response definition

7. "获取函数实例"

route definition

Url: /api/v1/functions/:id/instances
Method: GET
Request: FunctionInstancesRequest
Response: FunctionInstancesResponse

request definition

type FunctionInstancesRequest struct {
	ID string `path:"id"`
}

response definition

type FunctionInstancesResponse struct {
	Items []FunctionInstance `json:"items"`
}

跨实例聚合（集群模式）：本端点与 GET /api/v1/functions/instances 均以共享归属表（cluster_agent_owners）为在线全集——对端 server 实例持有的 agent 也计入，明细从共享 agent_sessions 快照表读取。归属对端实例的条目带 ownerInstance 字段标注（含两类：本地 registry 没有经快照表兜底拉出的，与本地存在的对端持有 DB 快照——后者是 30s 周期 refreshRemoteSnapshots 回灌的，并非本实例直连）；本实例自持/直连的 agent 该字段缺省。归属表不可达时静默回落本实例视图（全部按本实例渲染）。单实例部署（cluster.enabled=false）行为不变（纯本实例）。

8. "调用函数"

route definition

Url: /api/v1/functions/:id/invoke
Method: POST
Request: FunctionInvokeRequest
Response: FunctionInvokeResponse

request definition

type FunctionInvokeRequest struct {
	ID string `path:"id"`
	Params JSONValue `json:"params,optional"`
	Payload JSONValue `json:"payload,optional"`
	GameID string `json:"gameId,optional"` // 兼容字段；生效 scope 以 X-Game-ID/X-Env 请求头为准
	Env string `json:"env,optional"`     // 兼容字段；生效 scope 以 X-Game-ID/X-Env 请求头为准
	Mode string `json:"mode,optional"`
	Route string `json:"route,optional"`
	TargetServiceID string `json:"targetServiceId,optional"`
	HashKey string `json:"hashKey,optional"`
}

response definition

type FunctionInvokeResponse struct {
	TaskId           string      `json:"taskId"`
	Result           JSONValue   `json:"result,omitempty"`
	ApprovalID       string      `json:"approval_id,omitempty"`       // 审批请求 ID（当需要审批时返回）
	ApprovalRequired bool        `json:"approval_required,omitempty"` // 是否需要审批
	ApprovalWorkflow string      `json:"approval_workflow,omitempty"` // 审批流程类型（single_admin/two_person）
}

说明：

当函数政策需要审批时（RequireApproval=true），调用会创建审批请求并返回 ApprovalID
需要审批的调用不会立即执行，需等待审批通过后执行
ApprovalWorkflow 表示审批流程类型：
- single_admin: 单个管理员审批即可
- two_person: 需要双人审批

路由参数校验（2026-09-11 行为变更）：以下情形在 policy 检查之前直接返回 400 validation_failed，不再静默回落默认路由：

route: "targeted" 未提供 targetServiceId
route: "hash" 未提供 hashKey
route: "broadcast" 搭配 mode: "async"（广播无异步语义）
route 非法值（合法：lb（默认）/targeted/hash/broadcast）

错误语义：

503 service_unavailable：无可用 agent（本地与共享归属表均无候选）或 failover 耗尽全部候选（同步与 mode: async 同语义，lb 路由最多 3 次换候选重试，targeted/hash 语义指定唯一目标不重试）——可重试（agent 重新注册/归属表 TTL 过期后自愈）；多实例部署下选中远端候选时经 mesh 转发到 owner 实例执行，对调用方透明
400 validation_failed：路由参数缺失/冲突（见上），details 携具体字段

9. "获取函数权限"

route definition

Url: /api/v1/functions/:id/permissions
Method: GET
Request: FunctionPermissionsRequest
Response: FunctionPermissionsResponse

request definition

type FunctionPermissionsRequest struct {
	ID string `path:"id"`
}

response definition

type FunctionPermissionsResponse struct {
	Items []FunctionPermission `json:"items"`
}

10. "更新函数权限"

route definition

Url: /api/v1/functions/:id/permissions
Method: PUT
Request: FunctionPermissionsUpdateRequest
Response: FunctionPermissionsResponse

request definition

type FunctionPermissionsUpdateRequest struct {
	ID string `path:"id"`
	Permissions []FunctionPermission `json:"permissions"`
}

response definition

type FunctionPermissionsResponse struct {
	Items []FunctionPermission `json:"items"`
}

11. "发布函数"

route definition

Url: /api/v1/functions/:id/publish
Method: POST
Request: FunctionPublishRequest
Response: FunctionPublishResponse

request definition

type FunctionPublishRequest struct {
	ID string `path:"id"`
}

response definition

type FunctionPublishResponse struct {
	ApprovalId string `json:"approvalId,omitempty"` // 如果需要审批
	Published bool `json:"published"`
}

12. "批量复制函数"

route definition

Url: /api/v1/functions/batch-copy
Method: POST
Request: BatchCopyFunctionsRequest
Response: BatchCopyFunctionsResponse

request definition

type BatchCopyFunctionsRequest struct {
	FunctionIds []string `json:"function_ids"`
}

response definition

type BatchCopyFunctionsResponse struct {
	Updated int `json:"updated"`
	Failed []string `json:"failed"`
	Copied []string `json:"copied"` // 新复制的函数ID列表
}

17. "批量删除函数"

route definition

Url: /api/v1/functions/batch-delete
Method: POST
Request: BatchDeleteFunctionsRequest
Response: BatchDeleteFunctionsResponse

request definition

type BatchDeleteFunctionsRequest struct {
	FunctionIds []string `json:"function_ids"`
}

response definition

type BatchDeleteFunctionsResponse struct {
	Updated int `json:"updated"`
	Failed []string `json:"failed"`
}

18. "批量更新函数状态"

route definition

Url: /api/v1/functions/batch-update
Method: POST
Request: BatchUpdateFunctionsRequest
Response: BatchUpdateFunctionsResponse

request definition

type BatchUpdateFunctionsRequest struct {
	FunctionIds []string `json:"function_ids"`
	Enabled bool `json:"enabled"`
}

response definition

type BatchUpdateFunctionsResponse struct {
	Updated int `json:"updated"`
	Failed []string `json:"failed"`
}

19. "获取函数描述符列表"

route definition

Url: /api/v1/functions/descriptors
Method: GET
Request: DescriptorsRequest
Response: DescriptorsResponse

request definition

type DescriptorsRequest struct {
	Type string `form:"type,optional"`
	GameId string `form:"gameId,optional"`
}

response definition

type DescriptorsResponse struct {
	Items []Descriptor `json:"items"`
}

20. "获取待处理函数"

route definition

Url: /api/v1/functions/pending
Method: GET
Request: FunctionsPendingRequest
Response: FunctionsPendingResponse

request definition

type FunctionsPendingRequest struct {
}

response definition

type FunctionsPendingResponse struct {
	Items []PendingFunction `json:"items"`
}

21. "批量获取函数 OpenAPI"

route definition

Url: /api/v1/functions/_openapi-batch
Method: POST
Request: BatchGetSpecRequest
Response: map[string]OpenAPIOperation

request definition

type BatchGetSpecRequest struct {
	FunctionIDs []string `json:"function_ids"`
}

response definition

// key 为 function id，value 为对应的 OpenAPI Operation；未找到时返回 null
map[string]OpenAPIOperation

说明

该接口用于 Dashboard 批量读取函数 OpenAPI，避免逐个请求。
当前返回值直接透传注册表中的 OpenAPI operation 对象。

22. "获取函数契约变更历史"

route definition

Url: /api/v1/functions/:id/versions
Method: GET
Request: query page / pageSize
Response: ContractVersionsResult

response definition

type ContractVersionDiffEntry struct {
	Field    string                 `json:"field"`
	From     string                 `json:"from,omitempty"`
	To       string                 `json:"to,omitempty"`
	Change   string                 `json:"change,omitempty"` // 如 schema_replaced
	Findings []schemadiff.Finding   `json:"findings,omitempty"`
}

type ContractVersionItem struct {
	Seq          int64    `json:"seq"`
	Version      string   `json:"version,omitempty"`
	Source       string   `json:"source,omitempty"`
	SourceDigest string   `json:"sourceDigest,omitempty"`
	ChangeType   string   `json:"changeType"` // created|updated|removed
	Breaking     bool     `json:"breaking"`
	Actor        string   `json:"actor,omitempty"`
	CreatedAt    string   `json:"createdAt"`
	Diff         []ContractVersionDiffEntry `json:"diff,omitempty"`
}

type ContractVersionsResult struct {
	Items []ContractVersionItem `json:"items"`
	Total int64                 `json:"total"`
	Page  int                   `json:"page"`
	Size  int                   `json:"size"`
}

23. "获取函数契约版本快照"

route definition

Url: /api/v1/functions/:id/versions/:seq
Method: GET
Response: ContractVersionDetailResult（ContractVersionItem + snapshot，snapshot 为变更后的 FunctionSpec 投影；不存在返回 404）

24. "对比函数契约两个版本"

route definition

Url: /api/v1/functions/:id/versions/diff
Method: GET
Request: query from / to（版本 seq）
Response: ContractVersionDiffResult

type ContractVersionDiffResult struct {
	FromSeq  int64                      `json:"fromSeq"`
	ToSeq    int64                      `json:"toSeq"`
	Breaking bool                       `json:"breaking"`
	Changes  []ContractVersionDiffEntry `json:"changes"`
}

说明（版本历史）

判据与 UpsertContract 的「内容无变化跳过写」完全一致（同一 contractSemanticallyEqual）：重复注册相同内容不产生历史。
每函数保留上限 FunctionContractVersionRetention（当前 50 条），超出按最老淘汰。
历史写失败降级为告警不阻断注册（衍生审计数据；表由 goose 0029 + 启动期 MinimumRequiredVersion=29 保证存在）。
seq 无唯一索引（多实例并发注册允许并列，读取按 seq DESC, id DESC 稳定排序）。

25. "获取全部函数版本门槛"

route definition

Url: /api/v1/functions/version-floors
Method: GET
Response: 当前 game/env 下全部已配置门槛（未配置的函数不在返回中）

type versionFloorsListResponse struct {
	Floors map[string]string `json:"floors"` // functionId -> minVersion
}

26. "批量设置/清除函数版本门槛"

route definition

Url: /api/v1/functions/version-floor/batch
Method: POST
Permission: functions:manage（同单函数 PUT/DELETE）
Request:

type versionFloorBatchRequest struct {
	FunctionIds []string `json:"functionIds" binding:"required"` // trim + 去重后为空返回 400
	MinVersion  string   `json:"minVersion"`                     // 空串 = 批量清除（等价逐函数 DELETE）
}

Response: 部分成功语义（逐函数循环 Set/Delete，均幂等可重试，无事务）

type versionFloorBatchResponse struct {
	Updated    int      `json:"updated"`
	Failed     []string `json:"failed"`
	MinVersion string   `json:"minVersion,omitempty"` // 回显本次设置值
}

27. "获取函数历史版本索引"

route definition

Url: /api/v1/functions/version-history
Method: GET
Response: 当前 game/env 下每个函数历史出现过的契约版本（供版本门槛下拉选项，OPEN-ISSUES #26；无历史的函数不出现在返回中）

type functionVersionIndexResponse struct {
	Items []struct {
		FunctionID string   `json:"functionId"` // 字典序
		Versions   []string `json:"versions"`   // semver 数值降序，不可解析版本殿后
	} `json:"items"`
}

数据源为 function_contract_versions 的 distinct 聚合（30s TTL 内存缓存，无写失效——选项性数据，陈旧窗口有界，同资源分类聚合先例）。

说明（版本门槛）

函数级版本门槛是「UI 按函数配置的最低可注册函数版本」（比函数描述符自身 version，与 SDK 版本无关），判定语义见 docs/architecture/data-flow.md §「函数级最低版本（UI 按函数配置）」。
单函数三端点：GET/PUT/DELETE /api/v1/functions/:id/version-floor（PUT body {minVersion}，写需 functions:manage；DELETE 物理删行）。
批量 minVersion 非空时服务端先整包校验可解析（sdkversion.Parseable），非法 400 且零写入。
版本门槛落 game 库 function_version_floors 表（编号迁移 0030）；内存 registry（无 DB）退化为进程内 map。

函数政策 API（未接线）

函数政策（GET/PUT/DELETE /api/v1/functions/:function_id/policy）与系统政策（/api/v1/policies/*）端点当前未在生效路由（internal/handler/routes.go）注册（早期文档提及的并行注册文件已随路由收口移除），不对外提供。政策行为由函数合同的 risk/approval 字段与执行链路治理承载；本节历史文档已删除，待端点接线后再恢复。

补充端点

以下已注册端点是函数域 canonical 集合的一部分：

http

GET /api/v1/functions/{id}/analytics   # 函数调用分析
GET /api/v1/functions/instances        # 全量函数实例
GET /api/v1/functions/warnings         # 注册警告列表
GET /api/v1/functions/version-floors   # 全部函数版本门槛
GET /api/v1/functions/version-history  # 函数历史版本索引（门槛下拉选项，#26）
GET /api/v1/functions/:id/openapi      # 函数 OpenAPI spec（公开）
POST /api/v1/functions/_openapi-batch  # 批量获取 OpenAPI spec（公开）
GET /api/v1/openapi/spec               # 全局 OpenAPI 文档（公开）

函数 API ​

通用类型 ​

1. "获取函数列表" ​

2. "获取函数详情" ​

3. "删除函数" ​

4. "复制函数" ​

5. "禁用函数" ​

6. "启用函数" ​

7. "获取函数实例" ​

8. "调用函数" ​

9. "获取函数权限" ​

10. "更新函数权限" ​

11. "发布函数" ​

12. "批量复制函数" ​

17. "批量删除函数" ​

18. "批量更新函数状态" ​

19. "获取函数描述符列表" ​

20. "获取待处理函数" ​

21. "批量获取函数 OpenAPI" ​

说明 ​

22. "获取函数契约变更历史" ​

23. "获取函数契约版本快照" ​

24. "对比函数契约两个版本" ​

说明（版本历史） ​

25. "获取全部函数版本门槛" ​

26. "批量设置/清除函数版本门槛" ​

27. "获取函数历史版本索引" ​

说明（版本门槛） ​

函数政策 API（未接线） ​

补充端点 ​