GET/api/v1/catalogs/countries
匿名,需App公共头JSON 响应接入指南 ↗

获取支持的国家与地区

请求参数

供注册国家选择及资料编辑选择器使用。八项公共请求头全部必填,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尚未迁移到新接口,服务发布不等于客户端已经接入。