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
+16 -1
View File
@@ -1,3 +1,4 @@
// 本文件记录研究 API 的回归契约;测试注释描述实际断言,不代表本次已运行测试。
package research
import (
@@ -13,6 +14,7 @@ import (
"time"
)
// fixtureRepository 捕获调用参数和次数,并可模拟依赖失败或等到 context 被取消。
type fixtureRepository struct {
filters Filters
id int64
@@ -21,6 +23,7 @@ type fixtureRepository struct {
calls int
}
// List 只返回结构化空列表,wait 分支专门验证请求期限与槽位回收。
func (f *fixtureRepository) List(ctx context.Context, filters Filters) (Page, error) {
f.calls++
f.filters = filters
@@ -31,18 +34,21 @@ func (f *fixtureRepository) List(ctx context.Context, filters Filters) (Page, er
return Page{Items: []Paper{}, Topics: []string{}, PageSize: filters.PageSize}, f.err
}
// Get 保存请求 ID 并给出固定论文,不访问数据库。
func (f *fixtureRepository) Get(ctx context.Context, id int64) (Paper, error) {
f.calls++
f.id = id
return Paper{ID: "42", Title: "Original title", Authors: []string{}, Topics: []string{}, Sources: []Source{}}, f.err
}
// request 使用内存 recorder 执行路由,不启动监听端口。
func request(handler http.Handler, method, path string) *httptest.ResponseRecorder {
w := httptest.NewRecorder()
handler.ServeHTTP(w, httptest.NewRequest(method, path, nil))
return w
}
// TestAnonymousReadRoutes 通过假仓库验证匿名列表/详情、参数传递、JSON 空值与响应头,并拒绝写方法及未知项目。
func TestAnonymousReadRoutes(t *testing.T) {
f := &fixtureRepository{}
mux := http.NewServeMux()
@@ -70,6 +76,7 @@ func TestAnonymousReadRoutes(t *testing.T) {
}
}
// TestInvalidQueriesNeverReachRepository 逐项注入重复、未知、超限及非法 Unicode/ID 参数,要求 400 且仓库调用次数保持零。
func TestInvalidQueriesNeverReachRepository(t *testing.T) {
queries := []string{"unknown=1", "q=x&q=y", "q=%ff", "q=%00", "q=%zz", "page=0", "page=1001", "page=-1", "page=1.5", "page=01", "pageSize=51", "pageSize=0", "pageSize=9999999999999999999999", "searchIn=sql", "sort=published", "topic=arxiv:cs.LG", "q=" + url.QueryEscape(strings.Repeat("字", 201)), "q=" + url.QueryEscape(strings.Repeat("word ", 21))}
for _, query := range queries {
@@ -93,6 +100,7 @@ func TestInvalidQueriesNeverReachRepository(t *testing.T) {
}
}
// TestQueryDefaultsAndUnicode 验证多语言查询只裁剪两端空白,并采用文本搜索、最近排序和八条页大小。
func TestQueryDefaultsAndUnicode(t *testing.T) {
f, err := parseFilters("q=" + url.QueryEscape(" 论文 Graph "))
if err != nil || f.Query != "论文 Graph" || f.PageSize != 8 || f.SearchIn != "text" || f.Sort != "recent" {
@@ -100,11 +108,16 @@ func TestQueryDefaultsAndUnicode(t *testing.T) {
}
}
// databaseFailure 让测试模拟驱动 SQLState,同时让 Error 带私密文本以验证脱敏。
type databaseFailure string
func (failure databaseFailure) Error() string { return "private database error" }
// Error 故意返回私密说明,供响应脱敏断言检查。
func (failure databaseFailure) Error() string { return "private database error" }
// SQLState 模拟 PostgreSQL 驱动错误分类,不暴露其实际内部消息。
func (failure databaseFailure) SQLState() string { return string(failure) }
// TestStorageErrorsAreRedacted 注入缺行、取消和权限错误,检查状态码映射,同时确保私密数据库内容不会进入响应。
func TestStorageErrorsAreRedacted(t *testing.T) {
for _, test := range []struct {
err error
@@ -126,6 +139,7 @@ func TestStorageErrorsAreRedacted(t *testing.T) {
}
}
// TestConcurrencyAndTimeoutReleaseSlots 手动占满两个槽验证立即 429,再让假仓库等到超时,验证 504 后槽位被释放。
func TestConcurrencyAndTimeoutReleaseSlots(t *testing.T) {
s := &service{repository: &fixtureRepository{wait: true}, projects: map[string]string{"thesisly": "unused"}, slots: make(chan struct{}, 2), timeout: time.Millisecond}
mux := http.NewServeMux()
@@ -144,6 +158,7 @@ func TestConcurrencyAndTimeoutReleaseSlots(t *testing.T) {
}
}
// TestInvalidCursorsNeverReachRepository 验证坏编码、过长、筛选不符及重复游标在 HTTP 层拦截,不触发仓库查询。
func TestInvalidCursorsNeverReachRepository(t *testing.T) {
f := Filters{Query: "graph", Sort: "recent", SearchIn: "text", PageSize: 8}
valid := encodeCursor(f, position{ID: 42}, false)