接口

同一个 404 覆盖三种情况

第三行与第二行的区别只写进日志，不写进响应。日志字段见日志。

未带会话                 GET /notes/1      → 401
id 不存在                GET /notes/99999  → 404，正文 A
id 属于其他所属范围      GET /notes/2      → 404，正文 A（与上一行逐字节相同）
id 属于当前用户          GET /notes/1      → 200

错误体（404，越权与不存在通用）

里面不含栈、SQL、内部路径、具体是哪个条件不满足。这些内容只进日志。

{
  "error": {
    "code": "not_found",
    "message": "笔记不存在",
    "request_id": "01J9Z3K7QF8YV9M2N4P6R8T0W2"
  }
}

列表响应与分页

size 默认 20、上限 100，把超过 100 的请求返回 400 而不是静默截断。page 从 1 开始。排序必须带上唯一列，否则同一秒写入的行在两次查询里顺序不同，翻页会出现重复或漏行。

{
  "items": [
    {"id": 1, "title": "周记"}
  ],
  "page": 1,
  "size": 20,
  "total": 37
}

稳定的排序（写进查询，不写在注释里）

SELECT id, title, created_at
FROM notes
WHERE scope_id = ?
ORDER BY created_at DESC, id DESC
LIMIT ? OFFSET ?

internal/http/notes_contract_test.go

newTestServer 与 doRequest 是测试夹具，不属于本页内容。要看的是断言的对象：状态码、正文逐字节相等、以及「先查库再判断」这件事被日志验证。

func TestGetNoteCrossScopeLooksSameAsMissing(t *testing.T) {
	srv := newTestServer(t)          // 两个所属范围各一条数据
	missing := doRequest(t, srv, "GET", "/notes/99999", scopeA)
	other := doRequest(t, srv, "GET", "/notes/2", scopeA)

	if missing.Code != http.StatusNotFound || other.Code != http.StatusNotFound {
		t.Fatalf("两种情形都应为 404，实际 %d / %d", missing.Code, other.Code)
	}
	if missing.Body.String() != other.Body.String() {
		t.Fatalf("正文必须逐字节相同：\n%s\n---\n%s",
			missing.Body.String(), other.Body.String())
	}
}

func TestListEmptyScopeIs200WithEmptyArray(t *testing.T) {
	srv := newTestServer(t)
	resp := doRequest(t, srv, "GET", "/notes", scopeB) // scopeB 无数据
	if resp.Code != http.StatusOK {
		t.Fatalf("列表为空应为 200，实际 %d", resp.Code)
	}
	if !strings.Contains(resp.Body.String(), "\"items\":[]") {
		t.Fatalf("应为空数组而不是 null：%s", resp.Body.String())
	}
}

命令

接口契约测试与单元测试走同一条 go test，并进 make check。只跑这一次改动涉及的用例时用 -run。

go test ./internal/http/... -run 'TestGetNote|TestList'
go test ./... -race

助手交出来的样子

# 请求一：id 不存在
HTTP/1.1 404 Not Found
{"error": "not_found"}

# 请求二：id 存在，但属于其他范围
HTTP/1.1 403 Forbidden        ← 等于告诉调用方：这条记录存在
{"error": "forbidden"}