医院列表要在小程序里渲染,一张卡片只用到名称、等级、地址和医保标识,接口却默认返回二十来个字段。字段一多,响应体变大、渲染变慢,还容易把不该出现在前台的敏感信息一起带出去。
下面用数据鱼API提供的「全国医院查询」接口演示,调用的是「可查询字段列表」分支(
GET /v1/api/hospital/fields)。返回医院字段列表。
字段字典给出契约
GET /v1/api/hospital/fields 只需要 key 一个请求参数。返回 data.total 是字段总数,data.list 里每一项包含 field、label 和 brief:field 是字段名,label 是中文标签,brief 表示该字段是否属于精简模式返回的范围。
这份字典是所有裁剪操作的依据。查询、搜索、列表、详情、批量接口都支持 fields 参数,传的值必须是 field,不是 label。示例里 id、province、city 的 brief 都是 true,说明它们属于核心字段。
字段数量会随数据侧调整,字典的 total 是最直接的信号。如果某次上线后发现 total 变了,先别急着更新前端,确认新增字段是否涉及敏感信息,再决定要不要开放。
接入步骤
- 启动时拉一次字段字典,缓存到本地,记录
total。 - 按业务场景定义字段预设,例如卡片页、列表页、详情页各一套。
- 用
fields传预设,空格或逗号分隔都可以,最多 30 个。 - 在 CI 里做一次校验:预设里的字段名必须都存在于字典。
- 字典
total变化时,在后台提示,人工确认后再更新预设。
第三步的规则要记清楚:超出 30 个会截断,单个字段名超过 64 字符会被忽略,而且传错字段名不会报错,只是少返回。这意味着所有裁剪错误都是静默的,必须靠校验兜住。
另一个常见问题是字段顺序。fields 是白名单,不承诺返回顺序,前端不要按数组下标取值,一律按字段名访问。表格列的顺序放在前端配置里,和接口返回顺序解耦。
brief 还是 fields
brief 是省事的开关,适合“只要核心字段”的场景,前端不需要维护字段列表。fields 是精确控制,适合明确知道要哪几个字段的页面。两者同时传时以哪边为准,文档没有展开,团队内部约定只用一种更稳。
如果页面需要展示电话、邮箱、地址这类信息,先确认业务是否允许。接口能返回不代表应该展示,尤其是对 C 端页面,敏感字段要单独走审批或脱敏逻辑。
curl -s -G "$API_BASE/v1/api/hospital/list" \
--data-urlencode "key=$API_KEY" \
--data-urlencode "page=1" \
--data-urlencode "page_size=20" \
--data-urlencode "fields=id name level address insurance"
CARD_FIELDS = "id name level address insurance"
def hospital_cards(page=1):
r = requests.get(f"{API_BASE}/v1/api/hospital/list",
params={"key": API_KEY, "page": page,
"page_size": 20, "fields": CARD_FIELDS},
timeout=5)
return r.json()["data"]["list"]
几个坑
把 label 当字段名传,例如传“名称”而不是 name,整串会被忽略。字段名拼写差一个字母,同样静默失败,页面表现为空白。药品接口的 fields 只支持空格分隔,医院接口支持空格或逗号,跨接口复用代码时要注意这个差异。
还有,裁剪只影响返回字段,不会减少服务端的查询成本,别指望用它来优化接口耗时。它的价值在响应体大小和前端渲染。
字段预设最好版本化,和前端发布一起走。否则同一份代码在不同环境读到不同字典,页面字段会悄悄少几个,排查时很难想到是字典差异。
把字段字典当成前后端共同维护的契约,字段裁剪才不会变成一次性的手工活。字段字典没有分页参数,一次返回全部字段,可以在应用启动时加载,不必每次请求都拉。每次接口调整后重新拉一次字典,比凭记忆维护字段列表可靠。
示例接口由数据鱼API提供;不同版本的字段可能微调,正式接入前建议再核对一次文档。