SuperEggs

# Singo 使用手册

# Singo简介

# 单体，简单，够用

  • Singo是为了快速实现Restful API而搭建的。
  • Singo是单体架构而非微服务架构，用来实现中小型项目，他恰到好处。
  • Singo只引入最为必要的设计模式，你可以很快上手，把时间投入到你需要完成的工作中。
  • Singo选取了Golang社区最为流行的基础组件，配合Golang的威力，他只使用单机就可以为每天数百万用户提供稳定的服务。

# 特色

本项目已经整合了许多开发API所必要的组件：

  1. Gin: 轻量级Web框架，自称路由速度是golang最快的
  2. GORM: ORM工具。本项目需要配合Mysql使用
  3. Gin-Session: Gin框架提供的Session操作工具
  4. Go-Redis: Golang Redis客户端
  5. godotenv: 开发环境下的环境变量工具，方便使用环境变量
  6. Gin-Cors: Gin框架提供的跨域中间件
  7. 自行实现了国际化i18n的一些基本功能
  8. 本项目是使用基于cookie实现的session来保存登录状态的，如果需要可以自行修改为token验证

本项目已经预先实现了一些常用的代码方便参考和复用:

  1. 创建了用户模型
  2. 实现了/api/v1/user/register用户注册接口
  3. 实现了/api/v1/user/login用户登录接口
  4. 实现了/api/v1/user/me用户资料接口(需要登录后获取session)
  5. 实现了/api/v1/user/logout用户登出接口(需要登录后获取session)

本项目已经预先创建了一系列文件夹划分出下列模块:

  1. api文件夹就是MVC框架的controller，负责协调各部件完成任务
  2. model文件夹负责存储数据库模型和数据库操作相关的代码
  3. service负责处理比较复杂的业务，把业务代码模型化可以有效提高业务代码的质量（比如用户注册，充值，下单等）
  4. serializer储存通用的json模型，把model得到的数据库模型转换成api需要的json对象
  5. cache负责redis缓存相关的代码
  6. auth权限控制文件夹
  7. util一些通用的小工具
  8. conf放一些静态存放的配置文件，其中locales内放置翻译相关的配置文件

文档地址：Singo简介 - Singo (gourouting.github.io)

github：Singo简介 - Singo (github.com)

# 下载安装

安装前请确保你已经在电脑上安装好了Golang以及Git等最基础的开发工具

# 下载项目

首先你需要把项目下载到任何一个对于你舒服的位置

$ git clone https://github.com/bydmm/singo.git

无论你是通过git clone命令，还是直接下载并解压了项目的压缩包，你都可以把项目文件夹改成你需要的项目名称。

下面我会按照项目名为giligili作为例子

$ mv singo giligili

请不要把项目放在Golang安装目录的src子目录中！ Singo使用了Go Modules，你把项目放进src中会引起各种报错。 如果你执意这么做，请设置环境变量GO111MODULE=on。 如何设置环境变量，请参见参考资料中的《如何设置环境变量》这个小节。

# 配置环境变量来连接数据库

Singo使用了Mysql和Redis来存储数据，所以把Singo跑起来之前，你得安装好Mysql和Redis这两个服务。 很多人会忘记安装Redis，但是看到这里的你当然不会忘记。

# 创建.env文件

你需要在项目根目录创建.env文件来配置环境变量。项目中已经放置了.env.example这个文件作为一个例子，你可以把他的内容拷贝过来方便你创建这个文件。

MYSQL_DSN="db_user:db_passwd@tcp(127.0.0.1:3306)/db_name?charset=utf8&parseTime=True&loc=Local" # Mysql连接配置
REDIS_ADDR="127.0.0.1:6379" # Redis端口和地址
REDIS_PW=""                 # Redis连接密码
REDIS_DB=""                 # Redis库从0到10，不填即为0
SESSION_SECRE=""            # Seesion密钥，必须设置而且不要泄露
GIN_MODE="debug"            # 设置gin的运行模式，有 debug 和 release

我们可以特殊关注一下Mysql的连接配置，因为他确实有那么一点点复杂

MYSQL_DSN="db_user:db_passwd@tcp(127.0.0.1:3306)/db_name?charset=utf8&parseTime=True&loc=Local"

db_user是数据库账号 db_passwd是数据库密码 tcp(127.0.0.1:3306)是使用tcp协议，在ip为127.0.0.1的3306端口去访问数据库 db_name是数据库名 charset=utf8是设置数据库字符集 parseTime=True&loc=Local最后是设置时区为服务器时间

创建数据库的时候请把数据库的字符集设置为utf8_general_ci，这样才能比较好的支持中文。 否则到时候存进去和取出来的中文会变成乱码。 如果你还想让你的数据库支持emoji也就是🎂这样的特殊符号，你则需要把字符集设置为utf8mb4_general_ci，否则也emoji也是保存不进去的。

# 例子

我们在mysql中创建了名为giligili的数据库，并设置为utf8_general_ci这个字符集。 我们还给SESSION_SECRE这个变量赋值了一个比较复杂的随机字符串，这可以有效的保护我们Session数据。这个值非常机密，你一定不能把他泄露出去。

MYSQL_DSN="root:123456@tcp(127.0.0.1:3306)/giligili?charset=utf8&parseTime=True&loc=Local" # Mysql连接配置
REDIS_ADDR="127.0.0.1:6379" # Redis端口和地址
REDIS_PW=""                 # Redis连接密码
REDIS_DB=""                 # Redis库从0到10，不填即为0
SESSION_SECRE="fRJ%KVZVoq4Du4#*Rx" # Seesion密钥，必须设置而且不要泄露
GIN_MODE="debug"            # 设置gin的运行模式，有 debug 和 release

# 总结

.env文件只是一个帮你便捷的设置环境变量的途径而已，你其实可以通过很多方法来设置环境变量。只要环境变量设置的正确，没有这个文件也是可以运行singo的。

特别提一下，.env文件已经在git中被忽略掉了。这样会避免你错误的把这个充满秘密的文件被提交到GitHub。如果你好奇怎么做到的。可以参考godotenv的文档https://github.com/joho/godotenv，来观察他的实现方式。

生产环境如何设置环境变量，请参考后面的部署章节

← go-gin-api →