通知短信+运营短信,5秒速达,支持群发助手一键发送🚀高效触达和通知客户 广告
## 国际化 ### [](https://github.com/bolasblack/http-api-guide#语言标签)语言标签 [RFC 5646](http://tools.ietf.org/html/rfc5646) ([BCP 47](http://tools.ietf.org/html/bcp47)) 规定的语言标签的格式如下: ~~~ language-script-region-variant-extension-privateuse ~~~ 1. `language`:这部分使用的是 ISO 639-1, ISO 639-2, ISO 639-3, ISO 639-5 中定义的语言代码,必填 * 这个部分由 `primary-extlang` 两个部分构成 * `primary` 部分使用 ISO 639-1, ISO 639-2, ISO 639-3, ISO 639-5 中定义的语言代码,优先使用 ISO 639-1 中定义的条目,比如汉语 `zh` * `extlang` 部分是在某些历史性的兼容性的原因,在需要非常细致地区别 `primary` 语言的时候使用,使用 ISO 639-3 中定义的三个字母的代码,比如普通话 `cmn` * 虽然 `language` 可以只写 `extlang` 省略 `primary` 部分,但出于兼容性的考虑,还是**建议**加上 `primary` 部分 2. `script`: 这部分使用的是 [ISO 15924](http://www.unicode.org/iso15924/codelists.html) ([Wikipedia](http://zh.wikipedia.org/wiki/ISO_15924)) 中定义的语言代码,比如简体汉字是 `zh-Hans` ,繁体汉字是 `zh-Hant` 。 3. `region`: 这部分使用的是 ISO 3166-1 ([Wikipedia](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)) 中定义的地理区域代码,比如 `zh-Hans-CN` 就是中国大陆使用的简体中文。 4. `variant`: 用来表示 `extlang` 的定义里没有包含的方言,具体的使用方法可以参考 [RFC 5646](http://tools.ietf.org/html/rfc5646#section-2.2.5) 。 5. `extension`: 用来为自己的应用做一些语言上的额外的扩展,具体的使用方法可以参考 [RFC 5646](http://tools.ietf.org/html/rfc5646#section-2.2.6)。 6. `privateuse`: 用来表示私有协议中约定的一些语言上的区别,具体的使用方法可以参考 [RFC 5646](http://tools.ietf.org/html/rfc5646#section-2.2.7)。 其中只有 `language` 部分是必须的,其他部分都是可选的;不过为了便于编写程序,建议设计接口时约定语言标签的结构,比如统一使用 `language-script-region` 的形式( `zh-Hans-CN`, `zh-Hant-HK` 等等)。 语言标签是大小写不敏感的,但按照惯例,建议 `script` 部分首字母大写, `region` 部分全部大写,其余部分全部小写。 **有一点需要注意,任何合法的标签都必须经过 IANA 的认证,已通过认证的标签可以在[这个网页](http://www.iana.org/assignments/language-subtag-registry)查到。此外,网上还有一个非官方的[标签搜索引擎](http://people.w3.org/rishida/utils/subtags/)。** 相关资料: * ISO 639-1 Code List ([Wikipedia](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)) * [ISO 639-2 Code List](http://www.loc.gov/standards/iso639-2/php/code_list.php) ([Wikipedia](https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes)) * [ISO 639-3 Code List](http://www-01.sil.org/iso639-3/codes.asp?order=639_3&letter=%25) * [ISO 639-5 Code List](http://www.loc.gov/standards/iso639-5/id.php) ([Wikipedia](https://en.wikipedia.org/wiki/List_of_ISO_639-5_codes)) * [ISO 639-3 Macrolanguage Mappings](http://www-01.sil.org/iso639-3/macrolanguages.asp) ([Wikipedia](https://en.wikipedia.org/wiki/ISO_639_macrolanguage)) * [Relationship between ISO 639-3 and the other parts of ISO 639](http://www-01.sil.org/iso639-3/relationship.asp) * [网页头部的声明应该是用 lang="zh" 还是 lang="zh-cn"? - 知乎](http://www.zhihu.com/question/20797118) * [IETF language tag - Wikipedia](https://en.wikipedia.org/wiki/IETF_language_tag) * [语种名称代码](http://www.ruanyifeng.com/blog/2008/02/codes_for_language_names.html) :文中对带有方言( `extlang` )部分的标签介绍有误 * [Language tags in HTML and XML](http://www.w3.org/International/articles/language-tags/) * [Choosing a Language Tag](http://www.w3.org/International/questions/qa-choosing-language-tags) ### [](https://github.com/bolasblack/http-api-guide#时区)时区 客户端请求服务器时,如果对时间有特殊要求(如某段时间每天的统计信息),则可以参考 [IETF 相关草案](http://tools.ietf.org/html/draft-sharhalakis-httptz-05) 增加请求头 `Timezone` 。 ~~~ Timezone: 2007-06-12T23:48:22+0800 // OR Timezone: 1977-07-30T12:00:11+0200;;Europe/Athens ~~~ 时区的名称可以参考 [tz datebase](http://www.iana.org/time-zones)([Wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)) 。 如果客户端请求时没有指定相应的时区,则服务端默认使用 [UTC](http://zh.wikipedia.org/wiki/%E5%8D%8F%E8%B0%83%E4%B8%96%E7%95%8C%E6%97%B6) 时间返回相应数据。 PS 考虑到存在[夏时制](https://en.wikipedia.org/wiki/Daylight_saving_time)这种东西,所以不推荐客户端在请求时使用 Offset 。 ### [](https://github.com/bolasblack/http-api-guide#时间格式)时间格式 时间格式遵循 [ISO 8601](https://www.iso.org/obp/ui/#iso:std:iso:8601:ed-3:v1:en)([Wikipedia](https://en.wikipedia.org/wiki/ISO_8601)) 建议的格式: * 日期 `2014-07-09` * 时间 `14:31:22+0800` * 具体时间 `2007-11-06T16:34:41Z` * 持续时间 `P1Y3M5DT6H7M30S` (表示在一年三个月五天六小时七分三十秒内) * 时间区间 `2007-03-01T13:00:00Z/2008-05-11T15:30:00Z` 、 `2007-03-01T13:00:00Z/P1Y2M10DT2H30M` 、 `P1Y2M10DT2H30M/2008-05-11T15:30:00Z` * 重复时间 `R3/2004-05-06T13:00:00+08/P0Y6M5DT3H0M0S` (表示从2004年5月6日北京时间下午1点起,在半年零5天3小时内,重复3次) 相关资料: * [What's the difference between ISO 8601 and RFC 3339 Date Formats?](http://stackoverflow.com/questions/522251/whats-the-difference-between-iso-8601-and-rfc-3339-date-formats) * [JSON风格指南 - Google 风格指南(中文版)](https://github.com/darcyliu/google-styleguide/blob/master/JSONStyleGuide.md#%E5%B1%9E%E6%80%A7%E5%80%BC%E6%95%B0%E6%8D%AE%E7%B1%BB%E5%9E%8B) ### [](https://github.com/bolasblack/http-api-guide#货币名称)货币名称 货币名称可以参考 ISO 4217([Wikipedia](http://en.wikipedia.org/wiki/ISO_4217)) 中的约定,标准为货币名称规定了三个字母的货币代码,其中的前两个字母是 ISO 3166-1([Wikipedia](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)) 中定义的双字母国家代码,第三个字母通常是货币的首字母。在货币上使用这些代码消除了货币名称(比如 dollar )或符号(比如 $ )的歧义。 相关资料: * 《RESTful Web Services Cookbook 中文版》 3.9 节《如何在表述中使用可移植的数据格式》