[Go]二、RESTful API介绍和API流程和代码结构

目录

1、什么是API？

2、REST简介

3、RESTful RUI的设计

3.1、域名

3.2、版本(Versioning)

3.3、路径

3.4、名词VS动词

3.5、使用复数

3.6、HTTP动词

3.6.1、HTTP动词示例 

3.7、过滤信息(Filtering)

3.8、状态码(Status Codes)

3.9、返回结果及错误处理

4、RPC简介

5、HTTP API服务器启动流程

6、HTTP请求处理流程

7、HTTP 请求和响应格式介绍

8、项目目录结构

---

1、什么是API？

2、REST简介

REST代表表现层状态转移（REpresentational State Transfer），由Roy Eielding在他的论文中提出。REST是一种软件架构风格，不是技术框架，REST有一系列规范，满足这些规范的API均可称为RESTful API。REST规范中有如下几个核心：

1. REST中一切实体都被抽象成资源，每个资源有一个唯一标识——URL，所有的行为都应该是资源上的CRUD操作。
2. 使用标准的方法(GET/POST/PUT/DELETE)来更改资源的状态，常见的操作有：资源的增删改查操作。
3. 无状态：这里的无状态是指每个RESTful API请求都包含了所有足够完成本次操作的信息，服务器端无须保持Session。

无状态对于服务端的弹性扩容是很重要的

REST风格虽然适用于很多传输协议，但是在实际开发中，REST由于天生和HTTP协议相辅相成，因此HTTP协议已经成了实现RESTful API事实上的标准。在HTTP协议中通过POST、DELETE、PUT、GET方法对应REST资源的增、删、改、查操作，具体的对应关系如下：

3、RESTful RUI的设计

3.1、域名

3.2、版本(Versioning)

方法一： 应该将API的版本号放入URL。

方法二： 将版本号放在HTTP头信息中，但不如放入URL方便和直观。Github采用这种做法。

3.3、路径

路径又称"终点"（endpoint），表示API的具体网址，每个网址代表一种资源（resource）

3.4、名词VS动词

资源作为网址，只能有名词，不能有动词，而且所用的名词往往与数据库的表明对应。

3.5、使用复数

API中的名词应该使用复数。无论子资源或者所有资源。举例来说，获取产品的API可以这样定义：

3.6、HTTP动词

3.6.1、HTTP动词示例 

3.7、过滤信息(Filtering)

如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。下面是一些常见的参数。

3.8、状态码(Status Codes)

服务器向用户返回的状态码和提示信息，常见的有以下一些（方括号中是该状态码对应的HTTP动词）。

401：没有认证；403没有访问权限；404：没有url；

3.9、返回结果及错误处理

4、RPC简介

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

5、HTTP API服务器启动流程

1. 在启动一个 API 命令后，API 命令会首先加载配置文件，根据配置做后面的处理工作。

2. 通常会将日志相关的配置记录在配置文件中，在解析完配置文件后，就可以加载日志包初始化函数，来初始化日志实例，供后面的程序调用。

3. 接下来，初始化数据库实例，建立数据库连接，供后面对数据库的 CRUD 操作使用

4. 在建立完数据库连接后，需要设置 HTTP ，通常包括 3 方面的设置：
   • 设置Header
   • 注册路由
   • 注册中间件
5. 之后会调用 net/http 包的 ListenAndServe() 方法启动 HTTP 服务器
6. 在启动 HTTP 端口之前，程序会 go 一个协程，来 ping HTTP 服务器的 /sd/health 接口，如果程序成功启动，ping 协程在 timeout 之前会成功返回，如果程序启动失败，则 ping 协程最终会 timeout ，并终止整个程序。

解析配置文件、初始化Log，初始化数据库的顺序根据自己的喜好和需求来排即可。

        

6、HTTP请求处理流程

 

• 建立连接

客户端发送 HTTP 请求后，服务器会根据域名进行域名解析，就是将网站名称转变成 IP 地址：localhost -> 127.0.0.1，Linux hosts文件、DNS 域名解析等可以实现这种功能。之后通过发起 TCP 的三次握手建立连接。TCP三次连接请参考 TCP 三次握手详解及释放连接过程，建立连接之后就可以发送 HTTP 请求了。

• 接受请求

HTTP 服务器软件进程，这里指的是 API 服务器，在接收到请求之后，首先根据 HTTP 请求行的信息来解析到 HTTP方法和路径，在上图所示的报文中，方法是GET ，路径是 /index.html ，之后根据 API 服务器注册的路由信息（大概可以理解为：HTTP 方法 + 路径和具体处理函数的映射）找到具体的处理函数。

• 处理请求

在接收到请求之后，API 通常会解析 HTTP 请求报文获取请求头和消息体，然后根据这些信息进行相应的业务处理，HTTP 框架一般都有自带的解析函数，只需要输入 HTTP 请求报文，就可以解析到需要的请求头和消息体。通常情况下，业务逻辑处理可以分为两种：包含对数据库的操作和不包含对数据的操作。大型系统中通常两种都会有：

1.  包含对数据库的操作：需要访问数据库（增删改查），然后获取指定的数据，对数据处理后构建指定的响应结构体，返回响应包。数据库通常用的是 MySQL，因为免费，功能和性能也都能满足企业级应用的要求。

2. 不包含对数据库的操作：进行业务逻辑处理后，构建指定的响应结构体，返回响应包。

记录事务处理过程

在业务逻辑处理过程中，需要记录一些关键信息，方便后期 Debug 用。在 Go 中有各种各样的日志包可以用来记录这些信息。

7、HTTP 请求和响应格式介绍

请求头的组成 

1. 第一行必须是一个请求行（request line）

用来说明请求类型、要访问的资源以及所使用的 HTTP 版本

2. 紧接着是一个头部（header）小节 ，用来说明服务器要使用的附加信息

3. 之后是一个空行

4. 最后是请求数据（称之为主体：body） ，可以添加任意的其他数据

任意请求一个网站，使用F12可以查看到请求头和响应头信息。HTTP响应格式跟请求格式类似，也是由4个部分组成：状态行、消息报头

8、项目目录结构

gin不提供标准化的目录结构
admin.sh：一键停启
conf：配置文件目录
config：读取和解析配置文件的代码
db.sql：创建库表
docs：文档目录 -- 如：使用手册
handler：处理函数
router：路由 -- URL（和处理函数是映射关系）
main.go：入口文件
model：数据模型
pkg：写的一些通用处理代码
util：用来写一些小工具的文件
vendor：用来管理依赖包