41 lines
1.5 KiB
Python
41 lines
1.5 KiB
Python
|
"""统一响应信封（`docs/05` §3.3）。
|
||
|
|
|
||
|
|
§3.3 规定成功响应是 `{data, meta}`，列表的 `data` 为**纯数组**、游标与 `has_more` 放在
|
||
|
|
`meta` 里，并且明确「业务接口不得增加其他顶层字段」。
|
||
|
|
|
||
|
|
放在这里而不是各 Controller 各写一份：同一个偏差已经出现过两次 —— service 返回
|
||
|
|
`{items, next_cursor, has_more}`（或干脆只有 `data`）之后被直接当响应体返回，于是
|
||
|
|
`meta` 要么只剩 trace_id、要么整个缺失。同一份契约不该有多份实现。
|
||
|
|
"""
|
||
|
|
|
||
|
|
from __future__ import annotations
|
||
|
|
|
||
|
|
from typing import Any
|
||
|
|
|
||
|
|
from app.core.contracts import RequestContext
|
||
|
|
|
||
|
|
|
||
|
|
def envelope(data: object, context: RequestContext) -> dict[str, object]:
|
||
|
|
"""单资源 / 单对象的信封。"""
|
||
|
|
return {
|
||
|
|
"data": data,
|
||
|
|
"meta": {"trace_id": context.trace_id},
|
||
|
|
}
|
||
|
|
|
||
|
|
|
||
|
|
def list_envelope(page: dict[str, Any], context: RequestContext) -> dict[str, object]:
|
||
|
|
"""列表资源的信封：`data` 只放数组，分页元数据进 `meta`。
|
||
|
|
|
||
|
|
`page` 是 service 的内部结构 `{items, next_cursor, has_more}` —— service 不必改，
|
||
|
|
只是不再把它整体当 `data` 用。缺失的键按空值处理，因此只返回 `{"data": [...]}`
|
||
|
|
的旧 service 也不会炸。
|
||
|
|
"""
|
||
|
|
return {
|
||
|
|
"data": page.get("items") or [],
|
||
|
|
"meta": {
|
||
|
|
"trace_id": context.trace_id,
|
||
|
|
"next_cursor": page.get("next_cursor"),
|
||
|
|
"has_more": bool(page.get("has_more")),
|
||
|
|
},
|
||
|
|
}
|