前后端接口规范-------实体定义2

统一字段名

业务实体根据需求有不同的格式，但每个实体都 必须 有一个id字段用于唯一标识实体。id字段根据实际情况，可以使用 字符串 或 数字 作为字段类型，对于可能出现不可预期增长的实体，应当优先使用 字符串 作为id字段的类型。

对于有“名称”这一字段的实体，统一使用name作为名称的字段名。 不得 使用如adName这样的字段名。对于诸如“名称”这样具有通用意义的字段，使用统一的命名有助于代码的复用。

对于有实际新增、更新、删除等操作的实体，都 必须 有一个status字段用于标识实体的状态。status字段为 数字 类型，统一保留2个固定的值：0表示“已删除”，1表示“正常”。不同业务实体可在此基础上扩展其它状态，如“禁用”、“超量投放”等，但 不得 改变0和1两个状态的含义。
实体格式

一个实体通常会有3种类型的格式，建议在设计时给予详细的文档说明：

    简化字段，常用于在表格中呈现为一行，仅包含很少的字段。
    概要字段，常用于实体详情页面或报告页面的摘要性信息的展示，包含部分字段。
    全部字段，用于实体的修改、查看页面，需要全部的字段。

根据实体的字段数量、复杂程度，以上三种类型的格式可能相同也可能不同，应当在设计文档中进行有效的说明。
关联实体

对于实体的关联关系，标准 建议 采用嵌套的JSON对象，而非带前缀的字段来表示。

如对于“一个广告位所属的频道”这一字段，推荐的表示方法如下：

{
    "channel": {
        "id": 123456,
        "name": "测试频道"
    }
}

虽然也可以使用下面这种方式，但并不推荐：

{
    "channelId": 123456,
    "channelName": "测试频道"
}

使用嵌套对象有助于对关联实体字段的扩展，也更易于业务的切割和理解。
字段类型

对于实体的字段，应当严格按照字段的含义来决定类型，尽量避免“使用逗号分割的字符串表示数组”之类的情况发生。

如“一个用户的角色列表”这一字段，推荐的表示方法如下：

{
    "role": [1, 2, 3, 10]
}

不推荐以下方式：

{
    "role": "1,2,3,10"
}

良好的格式有助于对数据的进一步解析和格式化输出，可以避免不少重复分隔字符串、转换为文本、重新拼接字符串的操作。