获取支持的国家与地区¶
请求参数¶
供注册国家选择及资料编辑选择器使用。八项公共请求头全部必填,X-Client-Type=app、平台为ios或android;无需Bearer。携带凭证时仍校验凭证,不将无效凭证自动视作匿名。
无路径参数、查询参数和业务请求体,不分页。Accept-Language选择name的语言,支持中文、英文、日文、韩文及对应地区变体;未传或不支持时使用英文。每次都返回完整四语names。
JSON遵循AES/JWE协议:dev运行配置保留明文兼容,prod要求HTTPS和JWE;加密GET正文放在X-Budyoo-JWE。HTTP例外仅用于隔离固定码联调;当前公网正式域名使用HTTPS。成功及业务错误设置Cache-Control: no-store,合法请求ID回传X-Request-Id。
请求示例¶
base_url='https://api.budyoo.cn' # 当前dev;生产使用HTTPS和JWE
device_id='4d4ae3ea-6a4a-4f34-a292-8e94551851d7' # 同一安装持久保存
request_id=$(uuidgen | tr '[:upper:]' '[:lower:]')
timestamp="$(date +%s)000"
curl -i --fail-with-body \
"$base_url/api/v1/catalogs/countries" \
-H 'Accept: 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"
成功响应¶
HTTP 200。以下仅截取首项;当前完整目录包含249个国家/地区。
{
"code": "SUCCESS",
"message": "操作成功。",
"data": {
"version": "2026-11-03.1",
"language": "zh-CN",
"sort": "POPULARITY",
"rankingSource": "CONFIGURED",
"countries": [
{
"id": "cn",
"name": "中国",
"names": {"zh-CN": "中国", "en": "China", "ja": "中国", "ko": "중국"},
"flagUrl": "/api/v1/media/country-flags/cn",
"popularityRank": 1,
"aliases": ["中国", "China", "중국"]
}
]
},
"errors": []
}
| data字段 | 类型 | 可空 | 说明 |
|---|---|---|---|
| version | string | 否 | 国家名称、支持范围、图标或排序配置变更时更新的数据版本;不等于App版本 |
| language | string | 否 | 当前名称实际使用的语言:zh-CN、en、ja、ko |
| sort | string | 否 | 当前为POPULARITY,按热门排名返回 |
| rankingSource | string | 否 | 当前为CONFIGURED,表示服务端配置的初始热门优先级,并非实时用户热度统计 |
| countries | object[] | 否 | 当前支持的完整目录,按popularityRank升序 |
| countries[].id | string | 否 | 小写两位代码;保存用户资料时提交此值 |
| countries[].name | string | 否 | 当前语言下的国家/地区显示名称 |
| countries[].names | object | 否 | 四语名称映射,固定包含zh-CN、en、ja、ko四个string值 |
| countries[].flagUrl | string | 否 | 相对于API源站的绝对路径,访问方式见读取国旗;不是本机素材路径 |
| countries[].popularityRank | integer | 否 | 正整数,数值越小越靠前;当前排名唯一,不按国家名称或代码补充排序 |
| countries[].aliases | string[] | 否 | 检索别名;可与代码及四语名称一起在客户端搜索 |
排序由服务端统一决定,四种语言及国内/海外渠道共用同一顺序;客户端保持响应数组顺序,不再按英文、本地语言名称或国家代码二次排序。当前前十项为中国、美国、日本、韩国、英国、澳大利亚、加拿大、德国、法国、意大利。初始常用顺序沿用已确认的UI,其余条目也设置明确优先级;没有按注册人数、活跃度或点击次数实时计分。
失败响应¶
| HTTP | 业务码 | 条件/处理 |
|---|---|---|
| 400 | INVALID_CLIENT_HEADERS | 公共头缺失、重复或不合法 |
| 400 | ENCRYPTION_REQUIRED / INVALID_ENCRYPTED_REQUEST | 正式JSON缺少JWE,或密文不合法;其他加密错误见公共协议 |
| 401 | UNAUTHORIZED | 主动携带了无效或格式不合法的Bearer |
| 403 | FORBIDDEN | 客户端类型不是app |
| 426 | HTTPS_REQUIRED | 当前模式要求HTTPS,却使用明文HTTP |
错误结构遵循公共协议,字段错误在errors[].field/message,提示按请求语言返回。示例:
{"code":"INVALID_CLIENT_HEADERS","message":"对应当前语言的公共头校验提示","data":null,"errors":[]}
接入说明¶
- 使用本接口的
name或names展示国家名称,通过flagUrl获取服务器图标;不要求客户端预置这249项翻译或国旗。图片请求仍需公共头,禁止把凭证放进URL。 - 国家选择结果继续通过保存注册资料的
country字段提交;本接口不改变用户资料。注册完成后使用独立资料编辑接口,不使用注册保存入口;该接口的部署状态按其独立文档说明。 - 旧注册字典继续提供原有国家代码、别名、语言和兴趣,国家数组同步使用本接口的热门顺序,原字段保持兼容。新客户端的国家选择改用本独立接口。
- 数据和SVG随服务端版本发布,更新后重启生效;当前未实现后台热度编辑、实时热度统计或客户端自动迁移。
version变化时更新客户端自行保存的目录与图片缓存。 - 实现位于catalog的controller/service/storage/dto/model,跨模块只公开路径与既有字典校验契约;验证状态以本页顶部及交付说明为准。
验证:服务器整合构建272项Java测试全部通过,其中本次新增16项,覆盖四语与地区标签、英文回退、249项名称和国旗、热门顺序、旧字典兼容、公共头/客户端类型/凭证/HTTPS边界、双向JWE及错误目录拒绝。已随账号列表整合版本部署,完整278项Java回归通过;公网四语均返回249项且同源国旗读取成功。Flutter尚未迁移到新接口,服务发布不等于客户端已经接入。