关于restful:RESTful-API-参数限制

API 查看参数

常见 API

创立新的学生材料的接口如下：

Request

POST /students HTTP/1.1
Host www.school.com
Content-Type application/json

{
    "name": "tom",
    "age": 12,
    "ethnicity": "HAN"
}

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "code": 0,
    "message": "success",
    "data": {
        "id": 1,
        "name": "tom",
        "age": 12,
        "ethnicity": "HAN"
    }
}

蕴含 name \ age \ ethnicity 三个参数，其中 ethnicity 民族，须要做查看以防止输出零碎无奈解决的内容。

例如，前端须要将民族本地化为中文，零碎不反对的民族就无奈本地化为中文。

如果只有中国的 56 个民族，应用常量或者枚举都能够，实际中个别会选着应用枚举：

public enum Ethnicitiy {
    // 汉族
    HAN,
    // 蒙古族
    MONGOL, 
    // ... 
    // 基诺族
    JINO;
}

枚举中没有设置字段存储中文含意，是为了将编码和本地化解耦。如果只有繁多语言需要，请随便

Spring Web 模块默认反对枚举反序列化，谬误的数据将导致反序列化失败，这样就达到了查看参数的目标

数据耦合

这样的形式能实现性能，然而会使得数据和代码耦合。例如，须要新增一个 其余 other 选项，就须要更新代码并公布新版本

很多时候还会在前端存在相似的问题。例如，后端定义了枚举之后，APP 为了本地化显示会在代码中耦合相似枚举的数据。减少新的 其余 other 选项之后，后端和 APP 都须要公布新版本，然而 APP 是否降级是由用户抉择的，如果抉择强制降级会重大影响用户体验。

数据和代码的耦合，最显著的毛病就是批改数据须要批改代码。更通用的解释: 数据自身的含意不残缺，必须依附代码能力了解数据的含意

数据和代码耦合会造成数据通用性低，更换后端实现更简单，数据分析依赖于业务代码。以及，前端对接工作量减少

应用数据字典解耦

将服务器代码中的枚举转换成数据字典存入数据库，新增数据时只须要在数据库中增加记录即可

字典表 t_dict 存储民族数据如下：

留神，comment 是每行数据的正文，不能用于序列化或者本地化

01 \ 1 \ han \ HA 都能够作为编码，他们是等价的，在应用上没有区别。
例如，自定饮酒量规范如下：

一部分状况下，如果应用字符编码，英文母语开发者能够省略备注，非英文母语开发者须要备注阐明编码含意

编码 Encode

客户端遵循协定获取字典数据，将用户输出参数编码之后传给服务端

sequenceDiagram
participant c as Client 
participant s as Server
autonumber

c ->> s: Request dicts
s -->> c: Response dicts
c ->> c: Encode input parameters according to dicts
c ->> s: Submit data
s ->> s: Check if dicts is valid
s -->> c: Response OK

本地化 Localization

也叫解码 Decode，反对解码为多种语言就能够称之为本地化（与国际化同义）

服务端本地化

sequenceDiagram
participant c as Client 
participant s as Server
autonumber

c ->> s: Request data
s ->> s: Localize when decoding dicts
s -->> c: Response data

Request

申请时指定承受的语言

GET /students/1 HTTP/1.1
Host www.school.com
Accept: application/json
Accept-Language: zh-CN

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "id": 1,
    "name": "tom",
    "age": 12,
    "ethnicity": "汉族"
}

客户端端本地化

sequenceDiagram
participant c as Client 
participant s as Server
autonumber

c ->> s: Request data 
s -->> c: Response data
c ->> s: Request localization resoruces
s -->> c: Response localization resoruces
c ->> c: Localize when decoding dicts

申请数据

申请时指定承受的语言

GET /students/1 HTTP/1.1
Host www.school.com
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "id": 1,
    "name": "tom",
    "age": 12,
    "ethnicity": "han",
    "link_ethnicity_resources": "https://www.school.com/resources/localzations/ethnicities"
}

获取本地化资源

GET /resources/localzations/ethnicities HTTP/1.1
Host www.school.com
Accept: application/json
Accept-Language: zh-CN

依据申请的语言返回对应的本地化资源

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "han": "汉族",
    "mongol": "蒙古族",
    // ...
    "jino": "基诺族"
}

结尾

将数据和代码解耦，将本地化和编解码解耦，能够更好的反对变动的数据和需要。