API返回结果的参考规范

{
    data : { // 请求数据,对象或数组均可
        user_id: 123,
        user_name: "tutuge",
        user_avatar_url: "http://tutuge.me/avatar.jpg"
        ...
    },
    msg : "done", // 请求状态描述,调试用
    code: 1001, // 业务自定义状态码,如Http status 200但是用户未登录这样的业务代码。
    extra : { // 全局附加数据,字段、内容不定(如等级,经验的变化,可以作为全局的数据存在,区别于某次请求的具体data)
        type: 1,
        desc: "签到成功!"
    }
}

其中,code的定义要有一套规范,如:

// Code 业务自定义状态码定义示例
// 授权相关
1001: 无权限访问
1002: access_token过期
1003: unique_token无效
...
// 用户相关
2001: 未登录
2002: 用户信息错误
2003: 用户不存在
// 业务1
3001: 业务1XXX
3002: 业务1XXX
// ...

实践经验

命名风格统一

不管是驼峰式还是下划线式,统一就好。当然,按照目前的“大众规范”,还是统一小写加下划线比较好。
如:user_iduser_nameuser_age等。

语义清晰,遵守常用缩写

字段的名字最好能体现字段的类型,遵守一些“常用”的缩写,如:

// 字符串
user_name, task_desc, date_str, article_title, feed_content 等

// 数字
user_id, users_count, task_num, xxx_offset 等

// 日期

login_at, create_date, logout_time 等

// 布尔

is_done, is_vip, protected, can_read 等

// URL

user_avatar_url, thumb_url 等

// 数组

users, profiles, thumb_imgs 等

空值、空字段的处理

除了布尔类型的,其余的空值统一用null表示,客户端保证每种字段的null可以被正常处理。

给不同类型设置默认空值

除了null,还可以对字段设置“默认值”,如数字就是0,字符串就是空字符串"",数组就是空数组[],对象就是空对象{},这样有个好处就是可以避免很多客户端(Java、OC)处理空值(Null、nil、null)产生的异常。但是危害就是容易语义不明。还是要根据具体业务、前后端约定而定。

参考用Runtime的手段填充任意NSObject对象的nil属性,其实就是为对象空值统一设置默认值的。

布尔boolean值的处理

各种布尔值表示方式,如:

is_login:  true,

is_login:  "true",

is_login:  1

is_login:  "TRUE"

is_login:  "YES"

由于语言本身的限制、框架的处理方式,不对布尔类型的值做限制总觉得不踏实,像C、C++、Objective-C里面的布尔就是数字0和1,其它语言也都各自不一样,还有从数据库读写导致的布尔值类型不一致等。

所以,如果可以的话,最好一开始就对所有请求参数、结果的布尔值类型做限定,比如统一成数字0和1最好。

参考文章:
API返回结果设计经验与总结

你可能感兴趣的:(API返回结果的参考规范)