lzf_0626
8d79bd9767
"缺 meta"很容易被误判成"有"：X-Trace-ID 是**响应头**（中间件加），和 body 里的
meta.trace_id 是两件事；错误响应一直有 meta（异常处理器统一加），漏的只有成功路径。
核到三个端点在把 service 的内部结构直接当响应体返回：
- GET /conversations/{session_id}/messages → 裸 {"data": [...]}，meta 整个缺失，
游标也没地方放（§3.3 要求列表的 data 为纯数组、next_cursor/has_more 进 meta）
- POST /conversation-messages/{id}/feedback → 同样没有 meta
- GET /knowledge-references/{token} → 直接返回资源对象
改动：
- 新增 app/api/views/envelope.py，把 envelope / list_envelope 抽成一份公共实现，
风控链路改为复用它 —— 同一份契约写两遍的结果就是其中一处漏了 meta。
- ConversationService.messages 改为返回内部结构 {items, next_cursor, has_more}，
用 limit + 1 判断 has_more：只看"取满没取满"会把恰好等于 limit 的最后一页说成
还有下一页。next_cursor 取本页最后一条的 message_id —— 游标语义是"取更旧的一页"，
天然可续，集成测试本来就是这么翻页的。
- Controller 统一套信封，data 仍是数组、字段名不变，前端不需要改。
测试：新增 tests/unit/api/test_response_envelope.py，断言 set(body) == {"data","meta"}
（多或少一个顶层字段都会红），并覆盖 has_more / next_cursor / trace_id；
另更新两处既有断言（limit 20→21、feedback 返回裸对象）。
门禁：ruff 干净 / mypy 138 文件 / 696 unit+contract / 33 integration。
120 lines
4.4 KiB
Python
120 lines
4.4 KiB
Python
"""成功响应的统一信封（`docs/05` §3.3）。
|
||
|
||
§3.3 规定成功响应是 `{data, meta}`，列表的 `data` 为**纯数组**、`next_cursor` 与
|
||
`has_more` 放在 `meta` 里，并且明确「业务接口不得增加其他顶层字段」。
|
||
|
||
此前有三个端点漏了这件事，它们都是"service 直接把内部结构当响应体返回"：
|
||
|
||
- `GET /conversations/{session_id}/messages` → 裸 `{"data": [...]}`，`meta` 整个缺失，
|
||
游标也没有地方放；
|
||
- `POST /conversation-messages/{id}/feedback` → 同样没有 `meta`；
|
||
- `GET /knowledge-references/{token}` → 直接返回资源对象。
|
||
|
||
注意"缺 meta"很容易被误判成"有"：`X-Trace-ID` 是**响应头**（由中间件加），和 body 里的
|
||
`meta.trace_id` 是两件事；错误响应一直有 `meta`（异常处理器统一加），只有成功路径漏了。
|
||
所以这里断言的是 `set(body)`，多一个或少一个顶层字段都会红。
|
||
"""
|
||
|
||
from typing import Any
|
||
|
||
import pytest
|
||
from fastapi.testclient import TestClient
|
||
|
||
from app.api.controllers import conversations as conversations_controller
|
||
from app.api.controllers import knowledge as knowledge_controller
|
||
from app.api.dependencies.auth import build_request_context
|
||
from app.api.dependencies.database import get_session
|
||
from app.core.contracts import RequestContext
|
||
from app.main import create_app
|
||
|
||
TRACE = "trace-envelope"
|
||
|
||
|
||
async def resolve_context() -> RequestContext:
|
||
return RequestContext(
|
||
user_id="9001",
|
||
trace_id=TRACE,
|
||
permissions=("conversation:create", "conversation:feedback", "knowledge:reference:read"),
|
||
)
|
||
|
||
|
||
class StubConversationService:
|
||
def __init__(self, _session: Any) -> None:
|
||
pass
|
||
|
||
async def messages(
|
||
self, _session_id: str, _context: RequestContext, _limit: int, before: int | None = None
|
||
) -> dict[str, Any]:
|
||
del before
|
||
return {
|
||
"items": [
|
||
{
|
||
"message_id": "11",
|
||
"role": "user",
|
||
"content": "稳健型",
|
||
"created_at": "2026-09-10T00:00:00Z",
|
||
}
|
||
],
|
||
"next_cursor": "11",
|
||
"has_more": True,
|
||
}
|
||
|
||
async def feedback(
|
||
self,
|
||
_message_id: int,
|
||
_context: RequestContext,
|
||
_rating: int,
|
||
_feedback_type: str | None,
|
||
_feedback_content: str | None,
|
||
) -> dict[str, Any]:
|
||
return {"feedback_no": "fb-1", "status": "open"}
|
||
|
||
|
||
class StubKnowledgeService:
|
||
async def resolve(self, _context: RequestContext, _token: str) -> dict[str, Any]:
|
||
return {"knowledge_id": 7, "title": "个人投资者适当性管理指南"}
|
||
|
||
|
||
def envelope_client(monkeypatch: pytest.MonkeyPatch) -> TestClient:
|
||
monkeypatch.setattr(
|
||
conversations_controller, "ConversationService", StubConversationService
|
||
)
|
||
monkeypatch.setattr(knowledge_controller, "KnowledgeReferenceService", StubKnowledgeService)
|
||
application = create_app()
|
||
application.dependency_overrides[build_request_context] = resolve_context
|
||
application.dependency_overrides[get_session] = lambda: None
|
||
return TestClient(application)
|
||
|
||
|
||
def test_message_list_puts_cursor_in_meta(monkeypatch: pytest.MonkeyPatch) -> None:
|
||
with envelope_client(monkeypatch) as http:
|
||
response = http.get("/api/v1/conversations/session-1/messages", params={"limit": 20})
|
||
|
||
assert response.status_code == 200
|
||
body = response.json()
|
||
assert set(body) == {"data", "meta"}
|
||
assert isinstance(body["data"], list)
|
||
assert body["data"][0]["message_id"] == "11"
|
||
assert body["meta"] == {"trace_id": TRACE, "next_cursor": "11", "has_more": True}
|
||
|
||
|
||
def test_feedback_success_response_has_meta(monkeypatch: pytest.MonkeyPatch) -> None:
|
||
with envelope_client(monkeypatch) as http:
|
||
response = http.post("/api/v1/conversation-messages/11/feedback", json={"rating": 1})
|
||
|
||
assert response.status_code == 201
|
||
body = response.json()
|
||
assert set(body) == {"data", "meta"}
|
||
assert body["data"] == {"feedback_no": "fb-1", "status": "open"}
|
||
assert body["meta"] == {"trace_id": TRACE}
|
||
|
||
|
||
def test_knowledge_reference_success_response_has_meta(monkeypatch: pytest.MonkeyPatch) -> None:
|
||
with envelope_client(monkeypatch) as http:
|
||
response = http.get(f"/api/v1/knowledge-references/{'a' * 20}")
|
||
|
||
assert response.status_code == 200
|
||
body = response.json()
|
||
assert set(body) == {"data", "meta"}
|
||
assert body["meta"] == {"trace_id": TRACE}
|