读取国家与地区图标¶
请求参数¶
此地址由支持国家列表的flagUrl返回。八项公共请求头全部必填,X-Client-Type=app、平台为ios或android;无需Bearer。若主动携带凭证则仍会验证。
| 位置 | 字段 | 类型 | 必填 | 约束 |
|---|---|---|---|---|
| 路径 | countryCode | string | 是 | 支持目录内的小写两位代码,例如cn、us;不带.svg后缀 |
无查询参数、无请求体。图片是固定SVG媒体,不使用JSON/JWE封装,也不携带X-Budyoo-Encryption或X-Budyoo-JWE。生产要求HTTPS;当前固定码dev可按开发策略使用HTTP。与需要登录的用户头像读取相互独立,不开放其他媒体文件。
请求示例¶
base_url='https://api.budyoo.cn' # 当前dev;生产使用HTTPS
device_id='4d4ae3ea-6a4a-4f34-a292-8e94551851d7'
request_id=$(uuidgen | tr '[:upper:]' '[:lower:]')
timestamp="$(date +%s)000"
curl --fail-with-body \
"$base_url/api/v1/media/country-flags/cn" \
-H 'Accept: image/svg+xml, application/json' \
-H 'Accept-Language: zh-CN' \
-H 'X-Client-Type: app' \
-H 'X-Platform: android' \
-H 'X-App-Version: 1.0.0' \
-H 'X-App-Build: 1' \
-H 'X-Channel: dev' \
-H "X-Device-Id: $device_id" \
-H "X-Request-Id: $request_id" \
-H "X-Request-Timestamp: $timestamp" \
--output flag_cn.svg
成功响应¶
HTTP 200,正文为SVG文件字节,不包含code/message/data/errors包装。
| 响应头 | 值/说明 |
|---|---|
| Content-Type | image/svg+xml |
| Cache-Control | no-store |
| Content-Security-Policy | default-src 'none'; sandbox,不执行脚本或加载外部资源 |
| X-Request-Id | 回传合法请求ID |
图标采用现有正式UI中的国旗SVG,保持原始色彩与纵横比。国家目录加载时检查249项素材完整性;不会以空白图标响应缺失文件。
失败响应¶
| HTTP | 业务码 | 条件/处理 |
|---|---|---|
| 400 | INVALID_CLIENT_HEADERS | 公共头缺失、重复或不合法 |
| 400 | INVALID_ENCRYPTED_REQUEST | 媒体请求错误携带JWE加密模式 |
| 401 | UNAUTHORIZED | 主动携带了无效或格式错误的凭证 |
| 403 | FORBIDDEN | 客户端类型不是app |
| 404 | NOT_FOUND | 未支持的代码、大小写或后缀不符,例如zz、CN、cn.svg |
| 426 | HTTPS_REQUIRED | 当前模式要求HTTPS,却使用明文HTTP |
失败时按公共协议返回JSON与当前语言提示,例如:
{"code":"NOT_FOUND","message":"对应当前语言的资源不存在提示","data":null,"errors":[]}
接入说明¶
把flagUrl与当前API源站组合,不与文档站或UI预览站组合,也不要写死服务器IP。图片组件需支持SVG并附带公共头;国旗无需发送用户Token。
仅从服务器已发布的白名单目录读取,不支持上传、任意路径或外部URL代理。国旗和国家数据按同一版本发布;新客户端以国家列表的version管理本地显式缓存。服务端接口验证不代表Flutter已迁移到此图标入口。
验证:服务器272项整合Java回归全部通过,包含249个代码逐项HTTP处理链读取SVG、未知/大写/错误后缀404、公共头与客户端类型、错误凭证、HTTPS及媒体拒绝JWE。已随整合版本部署,完整278项Java回归通过;公网四种语言的目录及首项国旗读取成功,249项逐一读取仍以隔离回归为验证范围。