docs: annotate Foundry source and deployment lifecycle in Chinese [skip ci]

This commit is contained in:
2026-11-16 17:52:11 +08:00
parent 30829eeb86
commit 1090591503
123 changed files with 1279 additions and 3 deletions
+15
View File
@@ -16,12 +16,14 @@ import (
"unicode/utf8"
)
// Source 描述公开来源链接及其外部标识,不含内部数据库记录 ID。
type Source struct {
Label string `json:"label"`
URL string `json:"url"`
ExternalID string `json:"externalId"`
}
// Publication 是一次投稿的出版信息与最新决策证据;同一论文可对应多个投稿。
type Publication struct {
Venue string `json:"venue"`
Year int `json:"year"`
@@ -30,6 +32,7 @@ type Publication struct {
EvidenceURL string `json:"evidenceUrl,omitempty"`
}
// Paper 是公开 API 的论文投影;可空字段保留源数据缺省语义,ID 用字符串避免前端整数精度丢失。
type Paper struct {
ID string `json:"id"`
Title string `json:"title"`
@@ -44,6 +47,7 @@ type Paper struct {
Comments *string `json:"comments,omitempty"`
}
// Filters 由 parseFilters 验证;Cursor 是相同查询下的排序锚点,不是页码或 OFFSET。
type Filters struct {
Query string
SearchIn string
@@ -53,6 +57,7 @@ type Filters struct {
PageSize int
}
// Page 同时返回当前项、双向游标和语料主题列表;无后续页面的方向使用空字符串。
type Page struct {
Items []Paper `json:"items"`
NextCursor string `json:"nextCursor"`
@@ -63,11 +68,13 @@ type Page struct {
// Repository implementations must use a read-only transaction for each List,
// so its metadata and page describe the same database snapshot.
// Repository 将 HTTP 与存储解耦;List 的列表及元数据必须来自同一只读快照。
type Repository interface {
List(context.Context, Filters) (Page, error)
Get(context.Context, int64) (Paper, error)
}
// service 共享公开仓库和项目白名单,以 slots 对整个研究 API 限制并发数据库请求。
type service struct {
repository Repository
projects map[string]string
@@ -77,6 +84,7 @@ type service struct {
// Register adds only GET endpoints; no credentials or database errors are sent
// to anonymous callers. A nil repository leaves the existing server unchanged.
// Register 由 main 调用;没有研究库配置时不挂载路径,项目认证数据不参与公开语料查询。
func Register(mux *http.ServeMux, repository Repository, projects map[string]string) {
if repository == nil {
return
@@ -86,6 +94,7 @@ func Register(mux *http.ServeMux, repository Repository, projects map[string]str
mux.HandleFunc("GET /projects/{project}/research/papers/{id}", s.serve)
}
// reply 统一公开 JSON 的缓存和内容嗅探策略,写出后不再向调用方返回编码错误。
func reply(w http.ResponseWriter, status int, value any) {
w.Header().Set("Content-Type", "application/json")
w.Header().Set("Cache-Control", "no-store")
@@ -94,13 +103,16 @@ func reply(w http.ResponseWriter, status int, value any) {
_ = json.NewEncoder(w).Encode(value)
}
// reject 仅公开稳定错误码,数据库结构和底层错误内容不进入响应。
func reject(w http.ResponseWriter, status int, code string) {
reply(w, status, map[string]string{"error": code})
}
// 主题采用受限分类标识,正整数不接受符号或前导零,简化 ID 和页大小的解析。
var topicPattern = regexp.MustCompile(`^[A-Za-z][A-Za-z0-9.-]{0,79}$`)
var positiveInteger = regexp.MustCompile(`^[1-9][0-9]*$`)
// parseFilters 严格拒绝重复/未知参数;限制查询字数、词数和页大小后,再验证游标绑定。
func parseFilters(raw string) (Filters, error) {
f := Filters{SearchIn: "text", Sort: "recent", PageSize: 8}
values, err := url.ParseQuery(raw)
@@ -152,6 +164,7 @@ func parseFilters(raw string) (Filters, error) {
return f, err
}
// serve 在昂贵查询前验证项目与参数;详情不接受筛选参数,列表使用统一 Filters。
func (s *service) serve(w http.ResponseWriter, r *http.Request) {
if _, exists := s.projects[r.PathValue("project")]; !exists {
reject(w, 404, "not_found")
@@ -173,6 +186,7 @@ func (s *service) serve(w http.ResponseWriter, r *http.Request) {
reject(w, 400, "invalid_request")
return
}
// 无空闲槽位时立即返回 429,不排队积累匿名查询;defer 覆盖后续所有退出路径。
select {
case s.slots <- struct{}{}:
defer func() { <-s.slots }()
@@ -193,6 +207,7 @@ func (s *service) serve(w http.ResponseWriter, r *http.Request) {
reply(w, 200, result)
return
}
// SQLSTATE 57014 是数据库取消查询;与请求超时统一映射 504,其余依赖故障为 503。
var state interface{ SQLState() string }
switch {
case errors.Is(err, sql.ErrNoRows):