服务端 on 土土哥的技术 Blog

API返回结果设计经验与总结

Mon, 02 May 2016 02:44:49 +0000

前言

RESTful API的设计已经很成熟了，大家也都比较认可。本文也不再过多介绍RESTful API相关的知识，而是针对JSON型API的返回结果设计，总结下自己的经验。

结构

先来看看返回结果的结构示例：

{
 data : { // 请求数据，对象或数组均可
 user_id: 123,
 user_name: "tutuge",
 user_avatar_url: "http://tutuge.me/avatar.jpg"
 ...
 },
 msg : "done", // 请求状态描述，调试用
 code: 1001, // 业务自定义状态码
 extra : { // 全局附加数据，字段、内容不定
 type: 1,
 desc: "签到成功！"
 }
}

data字段 - 请求数据

首先是本次请求结果的数据data字段，其值为对象（字典）或数组均可以，根据业务而定。

如请求的是某个用户的个人profile信息，就可以是对象，对象里面是用户profile的键值对数据，如user_id: 123、user_name: "tutuge"等。

如果请求的是列表数据，就可以是数组，如请求用户列表：

data: [
 {user_id: 123, user_name: "tutuge"},
 {user_id: 321, user_name: "zekunyan"},
 ...
]

数组、对象，相互嵌套，灵活组合即可。

对于iOS来说，解析data字段是对象还是数组也很容易，在接收到JSON数据字典后，如AFNetworking的返回结果，对data判断其类型即可：

if ([jsonDict[@"data"] isKindOfClass:[NSDictionary class]]) {
 // JSON对象
} else if ([jsonDict[@"data"] isKindOfClass:[NSArray class]]) {
 // JSON数组
}

msg字段 - 请求状态描述，调试用

msg字段是本次请求的业务、状态描述信息，主要用于调试、测试等。

如“done”、“请求缺少参数！”

服务端可以自由发挥，开发人员看得懂就好。 -_-|||

code字段 - 业务自定义状态码

code字段，业务自定义的状态码。

其实是否要在API里面自定义业务状态码，非常有争议=。=，因为Http请求本身已经有了完备的状态码，再定义一套状态码直观上感受却是不对劲。但是实际开发中，确实发现自定义业务状态码的必要性，如一次成功的Http status 200的请求，可能由于用户未登录、登录过期而有不同的返回结果和处理方式，所以还是保留了code。

状态码的定义也最好有一套规范，如按照用户相关、授权相关、各种业务，做简单的分类：

// Code 业务自定义状态码定义示例

// 授权相关
1001: 无权限访问
1002: access_token过期
1003: unique_token无效
...

// 用户相关
2001: 未登录
2002: 用户信息错误
2003: 用户不存在

// 业务1
3001: 业务1XXX
3002: 业务1XXX

// ...

Code业务状态码最好是用常量定义的，当然有能力的动态配置更新更好，这里就不再详细说明。

Http的状态码参考：List of HTTP status codes

extra字段 - 全局附加数据

extra字段，用来表示全局的附加数据。

这个字段来源于之前做项目时，用户的操作（数据请求），会导致用户的等级、经验变化，而具体什么时候产生不确定，由服务端的规则决定，并且客户端要及时向用户展示变化，所以加上了extra字段。

在设计extra字段的时候，并没有对其结构内容做限制，所以比较灵活，但是还是要有个type字段，来做约束，如：

// 升级
type: 1,
show_msg: "恭喜您升级到XXX"

// 完成任务
type: 2,
task_desc: "达成XXX成就"

总的来说就是自由发挥，只要服务端、客户端相互沟通好即可。当然，也要避免乱用，保证真的需要全局附加数据才使用这个字段。

最佳实践

总结几点最佳实践。

规范统一的命名

命名风格统一

不管是驼峰式还是下划线式，统一就好。当然，按照目前的“大众规范”，还是统一小写加下划线比较好=。= 如：user_id，user_name，user_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可以被正常处理。

给不同类型设置默认空值

除了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最好。

然后在客户端和服务端统一设置常量、宏定义，定义布尔的类型，所有的参数、结果的布尔字段全部做强制约束。

时间、日期字段

时间的处理也是非常容易出错的，特别是遇上时区转换的时候。

强制GMT/UTC时间戳

一种做法就是强制所有时间参数只能传Unix时间戳，也就是标准GMT/UTC时间戳，然后由各自的客户端根据自己的时区、显示要求做处理后显示。

// 从服务器接收的时间数据
login_at: 1462068610

// 根据时区、显示要求转换，如北京时间
显示：2016年5月1日下午1点、1天前等

这样的话，客户端、服务端存储、读取时间都相当于处理纯数字。

使用ISO 8601带时区的时间日期字符串

使用Unix时间戳有个坏处，就是：

最早只能到1970/1/1 0:0:0GMT时间，一旦需求早于这个时间，时间戳就成了负数=。=
不方便人阅读。调试API的时候，开发人员不能直观看出具体时间，很不方便

所以，可以按照ISO 8601标准，用字符串保存、传输时间。

如果以YYYY-MM-DDThh:mm:ssTZD格式为准, 时间的形式就是1997-07-16T19:20:30+01:00，保存了时区信息，也方便阅读。

type类型的处理

API数据中免不了各种类型字段，如用户类型user_type、登录类型login_type等，类型的表示也可以分为数字、字符串两种。

数字表示类型

这个应该是最直接的方式了，客户端和服务端共同维护某个API下、某个数据类型中的type常量，靠文档约束。

字符串表示类型

数字的类型毕竟不利于直观阅读，如果可以的话，用字符串也是不错的，当然坏处就是代码里面就不能用Switch语句了（除了强大的Swift=。=）

// 如登录类型，QQ、微信、微博等
login_type: "qq",
login_type: "wechat",
login_type: "sina_weibo",

完整的URL

API里面的数据也会有URL类型的，一般来说如用户的头像、各种图片、音频等资源，都是以URL链接的形式返回的。

返回的URL一定要“完整”，主要指的是不要忘记URL里面的协议部分，也就是scheme部分。

像tutuge.me/imgs/1.jpg这种URL值，就是不完整的，没有指明网络协议，难道靠猜=。= 应该是http://tutuge.me/imgs/1.jpg。

总结

嗯，规范非常重要。:-D

RPC框架Thrift例子-PHP调用C++后端程序

Sun, 19 Apr 2015 09:04:56 +0000

更新

2016-02-22: Response对象不用主动创建。

前言

前段时间用了一下Facebook的开源RPC框架Thrift，做PHP客户端调用C++后端程序，真心觉得Thrift不错！

本文项目地址：https://github.com/zekunyan/ThriftDemo_PHP_CPP

先看看本文的例子示意图：

流程

PHP客户端发起请求，请求参数是“Request”类型，里面有studentID参数。
CPP服务端收到请求返回数据，返回类型为“Response”，里面包含了student的信息，此处只是简单的示例。

定义

什么是RPC

远程过程调用（英语：Remote Procedure Call，缩写为 RPC）是一个计算机通信协议。该协议允许运行于一台计算机的程序调用另一台计算机的子程序，而程序员无需额外地为这个交互作用编程。 – 维基百科 - 远程过程调用

通俗点讲，就是跨计算机、跨网络调用。

什么是Thrift

Apache Thrift 是Facebook实现的一种高效的、支持多种编程语言的远程服务调用(RPC)的框架。它采用接口描述语言定义并创建服务，支持可扩展的跨语言服务开发，所包含的代码生成引擎可以在多种语言中，如 C++, Java, Python, PHP, Ruby, Erlang, Perl, Haskell, C#, Cocoa, Smalltalk 等创建高效的、无缝的服务，其传输数据采用二进制格式，相对 XML 和 JSON 体积更小，对于高并发、大数据量和多语言的环境更有优势。 – Apache Thrift - 可伸缩的跨语言服务开发框架

开发流程

配置环境。C++的如CMake、make、g++；PHP的如php、php-fpm、Apache（Nginx）。
根据需求，编写thrift接口定义文件（IDL定义文件）。
使用thrift程序，为不同的语言生成代码。
根据需求，修改生成的代码（主要是Server端），编写实际的业务逻辑。
编译、部署。

Thrift的接口定义文件

在利用Thrift开发的过程中，重点就是编写接口定义文件。一般来说，接口定义文件决定了RPC过程中的通信数据结构、通信接口定义等。

总的来说，thrift的接口定义语法类似于C语言，包含了struct、enum、map、list等基础数据结构，同时支持大部分基本数据类型，如32位整型“i32”等。

详细的接口定义请参考：

看看本例子中的定义文件“TTG.thrift”：

namespace cpp TTG
namespace php TTG

enum ResponseState {
 StateOk = 0,
 StateError = 1,
 StateEmpty = 2
}

struct Request {
 1: i32 studentID = 0
}

struct Response {
 1: i32 studentID = 0,
 2: string name,
 3: list<string> infos,
 4: ResponseState state
}

service TTGService {
 Response getStudentInfo(1: Request request);
}

先定义命名空间，尽量减少命名冲突。
Request类型：PHP客户端请求的数据类型。
Response类型：CPP服务端返回的数据类型。
ResponseState枚举：定义返回的状态。
TTGService：服务接口定义。

生成对应语言的代码！

是的，生成代码！这是我觉得Thrift框架最“神奇”的地方。我们只需要执行几条命令，就可以根据接口定义文件“生成”对应语言的代码。然后我们只需要将对应的业务逻辑加入到生成的代码中即可。

如生成CPP服务端的代码：

thrift --gen cpp TTG.thrift

然后就会生成如下代码。

TTGService.cpp
TTGService.h
TTGService_server.skeleton.cpp
TTG_constants.cpp
TTG_constants.h
TTG_types.cpp
TTG_types.h

根据需要修改生成的代码

生成CPP、PHP端的代码以后，我们就可以根据需要修改、添加业务代码。

CPP服务端

在生成CPP的代码时，会生成一个“TTGService_server.skeleton.cpp”文件，这个就是我们的CPP服务端的代码“架子”。其中重点如下：

//实现调用的接口
class TTGServiceHandler : virtual public TTGServiceIf {
public:
TTGServiceHandler() {
 // Your initialization goes here
}

//接口实现部分，实现getStudentInfo这个接口的具体细节，如根据request创建、返回对应的response
void getStudentInfo(Response& _return, const Request& request) {
 // Your implementation goes here
 printf("getStudentInfo\n");
}

};
//...

我们将其改成：

void getStudentInfo(Response &_return, const Request &request) {
 // 输出请求参数
 cout<<"Request: "<<request.studentID<<endl;

 //填充数据，Response对象不用主动创建，进入函数时已经创建好了
 _return.studentID = request.studentID;
 _return.name = "tutuge";
 _return.infos.push_back("Info 1");
 _return.infos.push_back("Info 2");
 _return.state = ResponseState::StateOk;
}

至此，CPP服务端的编写就完成了，接下来我们只需要编译、链接，执行最终生成的可执行文件即可。

PHP客户端

PHP客户端的编写比较简单，直接参考代码吧：https://github.com/zekunyan/ThriftDemo_PHP_CPP/blob/master/PHP/client.php

编译、链接，运行

用CMake，或者直接编写makefile均可，保证Thrift装好就行了。

直接运行最后生成的可执行文件TTG.run即可。

从浏览器，或者直接运行client.php，即可看到如下输出：

object(TTG\Response)[9]
 public 'studentID' => int 100
 public 'name' => string 'tutuge' (length=6)
 public 'infos' =>
 array (size=2)
 0 => string 'Info 1' (length=6)
 1 => string 'Info 2' (length=6)
 public 'state' => int 0

总结

Thrift是个好东西！就是文档好少=。=