API 接口设计原则：RESTful 与 GraphQL

REST 的全称是 REpresentational State Transfer，是一种 Web API 的设计风格

一个 RESTful 风格的接口应该满足如下的 6 点原则：

• 统一接口：For example, the HTTP-based REST APIs make use of the standard HTTP methods (GET, POST, PUT, DELETE, etc.) and the URIs (Uniform Resource Identifiers) to identify resources
• 使用 client-server 架构解耦
• 无状态：server 不能保存与 client 的会话状态
• 可缓存的：响应数据应该声明自己能否被缓存
• 分层系统：采用反向代理服务器屏蔽 server 和 client
• 按需返回可执行代码：server 能够向 client 返回一段代码用以执行

• URL 中不要使用动词，动作交给 HTTP 的不同请求来区分
• 状态码必须准确，错误信息就要响应对应的错误状态码

下面使用 nodejs 编写了一个简单的 web 服务，提供了查询 user 的 RESTful get 接口：

var express = require('express');
var mysql = require("mysql");
var client = mysql.createConnection({host: '192.168.93.12',user: 'root',password: 'xxx',port: '3306',database: 'big_event',
});
client.connect();
var app = express();app.get("/user/:id", (req, res) => {let { id } = req.params;client.query(`select id, username, password, email from user where id=${id}`, (err, users) => {if (err) {console.warn(err);}if (users && users.length == 1) {res.send(users[0]);} else {res.send("wrong result");}});
})app.listen(5000, () => console.log('Now browse to localhost:5000/restful'));

对于上面的 API，使用 http://localhost:5000/user/1 即可获取到 id 为 1 的 user 信息

GraphQL 是一个用于 API 的查询语言，是一个使用基于类型系统来执行查询的服务端运行时

用 GraphQL 将上面的查询接口重写如下：

const { graphqlHTTP } = require('express-graphql');
const { buildSchema } = require('graphql');// 定义 GraphQL schema
const schema = buildSchema(`type User {id: Intusername: Stringpassword: Stringemail: String}type Query {user(id: Int!): User}
`);// 定义 resolver 函数，用于处理查询
const root = {user: ({ id }) => {return new Promise((resolve, reject) => {client.query(`SELECT id, username, password, email FROM user WHERE id = ${id}`, (err, result) => {if (err) {reject(err);} else {resolve(result[0]);}});});}
};const app = express();app.use('/graphql', graphqlHTTP({schema: schema,rootValue: root,graphiql: true // 启用 GraphiQL 可视化工具
}));app.listen(5000, () => {console.log('GraphQL Server is running on http://localhost:5000/graphql');
});

启动后，我们在浏览器中能够访问到一个调试界面：

输入查询条件：

{user(id: 1) {idusernamepassword}
}

就可以得到查询结果：

{"data": {"user": {"id": 1,"username": "wangba","password": "124bd1296bec0d9d93c7b52a71ad8d5b"}}
}