基于 Golang Web 框架 Gin 搭建 RESTful API 服务

1. 账号系统 API 功能简介

技术雷达

业务功能

apiserver

API 服务器状态检查
登录用户
新增用户
删除用户
更新用户
获取指定用户的详细信息
获取用户列表

运行环境

CentOS 7.5.1804

2. RESTful API 简介

RPCRESTJSONXMLProtobufgRPC + ProtobufREST + JSON

REST 简介

REST 代表表现层状态转移（REpresentational State Transfer），是一种软件架构风格，不是技术框架。

REST 有一系列规范，满足这些规范的 API 均可称为 RESTful API，核心规范如下：

URICRUDRESTful API

无状态对于服务端的弹性扩容来说至关重要

POSTDELETEPUTGETCRUD

RPC 简介

远程过程调用（Remote Procedure Call，RPC）是一个计算机通信协议，它允许运行于一台计算机的程序调用另一台计算机的子程序，而程序员无需额外为这个交互操作编程。

RPC 的调用过程如下：

ClientClient StubClient StubMarshallingClientServerServerServer StubServer StubUnmarshallingServer StubClient

REST vs RPC

RPC 相比于 REST 的优点主要有以下三点：

RPC+ProtobufRESTRESTRPC+ProtobufRESTRPCRPC

而 REST 相比于 RPC 也有很多优势：

RESTRESTRPCRPCJSONREST

媒体类型选择

JSON

3. API 流程和代码结构

HTTP API 服务器启动流程

HTTP 请求处理流程

HTTP 请求和响应格式介绍

request lineheaderbody

HTTP 响应格式与请求格式类似，也是由四部分组成：状态行、消息报头、空行和响应数据

目录结构

├── admin.sh                     # 进程的start|stop|status|restart控制文件
├── conf                         # 配置文件统一存放目录
│   ├── config.yaml              # 配置文件
│   ├── server.crt               # TLS配置文件
│   └── server.key
├── config                       # 专门用来处理配置和配置文件的Go package
│   └── config.go                 
├── db.sql                       # 在部署新环境时，可以登录MySQL客户端，执行source db.sql创建数据库和表
├── docs                         # swagger文档，执行 swag init 生成的
│   ├── docs.go
│   └── swagger
│       ├── swagger.json
│       └── swagger.yaml
├── handler                      # 类似MVC架构中的C，用来读取输入，并将处理流程转发给实际的处理函数，最后返回结果
│   ├── handler.go
│   ├── sd                       # 健康检查handler
│   │   └── check.go 
│   └── user                     # 核心：用户业务逻辑handler
│       ├── create.go            # 新增用户
│       ├── delete.go            # 删除用户
│       ├── get.go               # 获取指定的用户信息
│       ├── list.go              # 查询用户列表
│       ├── login.go             # 用户登录
│       ├── update.go            # 更新用户
│       └── user.go              # 存放用户handler公用的函数、结构体等
├── main.go                      # Go程序唯一入口
├── Makefile                     # Makefile文件，一般大型软件系统都是采用make来作为编译工具
├── model                        # 数据库相关的操作统一放在这里，包括数据库初始化和对表的增删改查
│   ├── init.go                  # 初始化和连接数据库
│   ├── model.go                 # 存放一些公用的go struct
│   └── user.go                  # 用户相关的数据库CURD操作
├── pkg                          # 引用的包
│   ├── auth                     # 认证包
│   │   └── auth.go
│   ├── constvar                 # 常量统一存放位置
│   │   └── constvar.go
│   ├── errno                    # 错误码存放位置
│   │   ├── code.go
│   │   └── errno.go
│   ├── token
│   │   └── token.go
│   └── version                  # 版本包
│       ├── base.go
│       ├── doc.go
│       └── version.go
├── README.md                    # API目录README
├── router                       # 路由相关处理
│   ├── middleware               # API服务器用的是Gin Web框架，Gin中间件存放位置
│   │   ├── auth.go 
│   │   ├── header.go
│   │   ├── logging.go
│   │   └── requestid.go
│   └── router.go
├── service                      # 实际业务处理函数存放位置
│   └── service.go
├── util                         # 工具类函数存放目录
│   ├── util.go 
│   └── util_test.go
└── vendor                         # vendor目录用来管理依赖包
    ├── github.com
    ├── golang.org
    ├── gopkg.in
    └── vendor.json