基于 Go 语言构建企业级的 RESTful API 服务 企业级go gin 开发框架 附带源码

 

本⼩册所实现的功

本⼩册所实现的 API 功能（项目源码 https://github.com/qq601046124/golang-gin-api）

能

本⼩册通过实现⼀个账号系统，来演⽰如何构建⼀个真实的API服务器，构建⽅法和技术是笔者根据多年的⼤型API服务器开发经验不断优化沉淀⽽成。通过实战展⽰了API构建过程中各个流程（准备

->设计->开发->测试->部署）的实现⽅法，⼩册涵盖的内容如下（包括但不限于）：

详细为：

准备阶段

如何安装和配置Go开发环境

如何安装和配置VimIDE

设计阶段

如何做数据库的CURD操作

如何⾃定义错误Code

如何读取和返回HTTP请求

如何进⾏业务逻辑开发

如何对请求插⼊⾃⼰的处理逻辑

如何进⾏API⾝份验证

如何进⾏HTTPS加密

如何⽤Makefile管理API源码

如何给API命令添加版本功能

如何管理API命令

部署阶段

如何⽤Nginx部署API服务

如何做API⾼可⽤

通过以上各功能的介绍，读者可以完整、系统地学习API构建⽅法和技巧，笔者也会在⽂章中融⼊⾃⼰的开发经验以供读者参考。

账号系统业务功能

本⼩册为了演⽰，构建了⼀个账号系统（后⾯统称为apiserver），功能如下：

API服务器状态检查

登录⽤户

新增⽤户

删除⽤户

⼩结

本⼩节介绍了⼩册所要实现的API功能，以及API系统的业务功能，让读者在实战前对⼩册所要构建的系统有个整体了解，以便于接下来的学习。⼩册每⼀节都会提供源码，供读者学习参考。

RESTfulAPI介绍

什么是API

API（ApplicationProgrammingInterface，应⽤程序编程接⼜）是⼀些预先定义的函数或者接⼜，⽬的是提供应⽤程序与开发⼈员基于某软件或硬件得以访问⼀组例程的能⼒，⽽又⽆须访问源码，或理解

内部⼯作机制的细节。

要实现⼀个API服务器，⾸先要考虑两个⽅⾯：API风格和媒体类型。Go语⾔中常⽤的API风格是RPC和REST，常⽤的媒体类型是JSON、XML和Protobuf。在GoAPI开发中常⽤的组合是gRPC+

Protobuf和REST+JSON。

REST简介

REST代表表现层状态转移（REpresentationalStateTransfer），由RoyFielding在他的论⽂中提出。REST是⼀种软件架构风格，不是技术框架，REST有⼀系列规范，满⾜这些规范的API均可称为

GET⽅法来对应REST资源的增、删、改、查操作，具体的对应关系如下：

HTTP⽅法 ⾏为 URI ⽰例说明

GET 获取资源列表 /users 获取⽤户列表

GET 获取⼀个具体的资源 /users/admin 获取admin⽤户的详细信息

POST 创建⼀个新的资源 /users 创建⼀个新⽤户

PUT 以整体的⽅式更新⼀个资源 /users/1 更新id为1的⽤户

DELETE 删除服务器上的⼀个资源 /users/1 删除id为1的⽤户

RPC简介

根据维基百科的定义：远程过程调⽤（RemoteProcedureCall，RPC）是⼀个计算机通信协议。该协议允许运⾏于⼀台计算机的程序调⽤另⼀台计算机的⼦程序，⽽程序员⽆须额外地为这个交互作⽤编

程。

4. Server端接收到消息后，将消息传递给ServerStub

5. ServerStub将消息解包（也叫Unmarshalling）得到参数

6. ServerStub调⽤服务端的⼦程序（函数），处理完后，将最终结果按照相反的步骤返回给Client

Stub负责调⽤参数和返回值的流化（serialization）、参数的打包解包，以及负责⽹络层的通信。Client端⼀般叫Stub，Server端⼀般叫Skeleton。

RESTvsRPC

在做API服务器开发时，很多⼈都会遇到这个问题——选择REST还是RPC。RPC相⽐REST的优点主要有3点：

1. RPC+Protobuf采⽤的是TCP做传输协议，REST直接使⽤HTTP做应⽤层协议，这种区别导致REST在调⽤性能上会⽐RPC+Protobuf低

2. RPC不像REST那样，每⼀个操作都要抽象成对资源的增删改查，在实际开发中，有很多操作很难抽象成资源，⽐如登录操作。所以在实际开发中并不能严格按照REST规范来写API，RPC就不存

在这个问题

3. RPC屏蔽⽹络细节、易⽤，和本地调⽤类似

这⾥的易⽤指的是调⽤⽅式上的易⽤性。在做RPC开发时，开发过程很烦琐，需要先写⼀个DSL描述⽂件，然后⽤代码⽣成器⽣成各种语⾔代码，当描述⽂件有更改时，必须重新定义和编

在实际开发中，严格按照REST规范来写很难，只能尽可能RESTful化。

其实业界普遍采⽤的做法是，内部系统之间调⽤⽤RPC，对外⽤REST，因为内部系统之间可能调⽤很频繁，需要RPC的⾼性能⽀撑。对外⽤REST更易理解，更通⽤些。当然以现有的服务器性能，如

果两个系统间调⽤不是特别频繁，对性能要求不是⾮常⾼，以笔者的开发经验来看，REST的性能完全可以满⾜。本⼩册不是讨论微服务，所以不存在微服务之间的⾼频调⽤场景，此外REST在实际开发

中，能够满⾜绝⼤部分的需求场景，所以RPC的性能优势可以忽略，相反基于REST的其他优势，笔者更倾向于⽤REST来构建API服务器，本⼩册正是⽤REST风格来构建API的。

媒体类型选择

媒体类型是独⽴于平台的类型，设计⽤于分布式系统间的通信，媒体类型⽤于传递信息，⼀个正式的规范定义了这些信息应该如何表⽰。HTTP的REST能够提供多种不同的响应形式，常见的是XML和

JSON。JSON⽆论从形式上还是使⽤⽅法上都更简单。相⽐XML，JSON的内容更加紧凑，数据展现形式直观易懂，开发测试都⾮常⽅便，所以在媒体类型选择上，选择了JSON格式，这也是很多⼤公

司所采⽤的格式。

⼩结

本⼩节介绍了软件架构中API的实现⽅式，并简单介绍了相应的技术，通过对⽐，得出本⼩册所采⽤的实现⽅式：API风格采⽤REST，媒体类型选择JSON。通过本⼩节的学习，读者可以了解⼩册所构

HTTPAPI服务器启动流程

如上图，在启动⼀个API命令后，API命令会⾸先加载配置⽂件，根据配置做后⾯的处理⼯作。通常会将⽇志相关的配置记录在配置⽂件中，在解析完配置⽂件后，就可以加载⽇志包初始化函数，来初

始化⽇志实例，供后⾯的程序调⽤。接下来会初始化数据库实例，建⽴数据库连接，供后⾯对数据库的CRUD操作使⽤。在建⽴完数据库连接后，需要设置HTTP，通常包括3⽅⾯的设置：

1. 设置Header

2. 注册路由

3. 注册中间件

之后会调⽤net/http包的ListenAndServe()⽅法启动HTTP服务器。

在启动HTTP端⼜之前，程序会go⼀个协程，来pingHTTP服务器的/sd/health接⼜，如果程序成功启动，ping协程在timeout之前会成功返回，如果程序启动失败，则ping协程最终会timeout，并终

⽌整个程序。

解析配置⽂件、初始化Log、初始化数据库的顺序根据⾃⼰的喜好和需求来排即可。

HTTP服务器软件进程，这⾥指的是API服务器，在接收到请求之后，⾸先根据HTTP请求⾏的信息来解析到HTTP⽅法和路径，在上图所⽰的报⽂中，⽅法是GET，路径是/index.html，之后根据API

服务器注册的路由信息（⼤概可以理解为：HTTP⽅法+路径和具体处理函数的映射）找到具体的处理函数。

3.处理请求

在接收到请求之后，API通常会解析HTTP请求报⽂获取请求头和消息体，然后根据这些信息进⾏相应的业务处理，HTTP框架⼀般都有⾃带的解析函数，只需要输⼊HTTP请求报⽂，就可以解析到需要

的请求头和消息体。通常情况下，业务逻辑处理可以分为两种：包含对数据库的操作和不包含对数据的操作。⼤型系统中通常两种都会有：

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

业级应⽤的要求。

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

4.记录事务处理过程

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

HTTP响应格式跟请求格式类似，也是由4个部分组成：状态⾏、消息报头、空⾏和响应数据。

⽬录结构

├── admin.sh # 进程的start|stop|status|restart控制⽂件

├── conf # 配置⽂件统⼀存放⽬录

│ ├── config.yaml # 配置⽂件

│ ├── server.crt # TLS配置⽂件

├── config # 专⻔⽤来处理配置和配置⽂件的Go package

├── db.sql # 在部署新环境时，可以登录MySQL客户端，执⾏source db.sql创建数据库和表

│ ├── create.go # 新增⽤户

│ ├── auth # 认证包

│ ├── constvar # 常量统⼀存放位置

│ ├── errno # 错误码存放位置