Singo 中文帮助文档

Question

单体，简单，够用

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

下载安装

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

下载项目

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

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

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

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

$ mv singo giligili

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

修改包名

修改 go.mod 文件

包名在项目的go.mod文件中

module singo

go 1.12

require (
	github.com/gin-contrib/cors v1.3.0
	github.com/gin-contrib/sessions v0.0.0-20190512062852-3cb4c4f2d615
	github.com/gin-gonic/gin v1.4.0
	github.com/go-redis/redis v6.15.3+incompatible
	github.com/jinzhu/gorm v1.9.10
	github.com/joho/godotenv v1.3.0
	golang.org/x/crypto v0.0.0-20190701094942-4def268fd1a4
	gopkg.in/go-playground/validator.v8 v8.18.2
	gopkg.in/yaml.v2 v2.2.2
)

你需要把第一行的

module singo

修改为

module giligili

这样你的包名就修改完成了

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

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 run main.go就可以把项目跑起来了。
然后go modoules会自动把你缺失的包安装好。

$ go run main.go   
finding github.com/gin-contrib/sessions latest
finding github.com/gin-contrib/sessions/cookie latest
finding golang.org/x/crypto/bcrypt latest
finding github.com/jinzhu/gorm/dialects/mysql latest
finding golang.org/x/crypto latest
finding github.com/jinzhu/gorm/dialects latest

如果你项目没有成功启动，绝大部分情况下是环境变量配置不成功，导致你要么连不上mysql，要么连不上redis

如何设置环境变量

Linux 系统或者 OSX

设置临时环境变量

如果你想临时的设置一次环境变量，你可以通过在命令行中使用export命令来完成，下面是为Go mod设置镜阿里云高速镜像代理的方法。

$ export GOPROXY=https://mirrors.aliyun.com/goproxy/

export是指令，代表需要设置环境变量。
GOPROXY是变量名，值被设置为https://mirrors.aliyun.com/goproxy/

临时环境变量只能在当前这次你启动的命令行终端中生效。
只要你退出当前的终端，开启新的终端，这次的设置就会失效

设置永久的环境变量

我们的攻略主要是针对开发环境，所以我们讲解如何改变你当前用户的环境变量。

$ echo 'export GOPROXY=https://mirrors.aliyun.com/goproxy/' >> ~/.bashrc

当你每次启动新终端的时候，操作系统都会执行~/.bashrc这个文件内的所有指令。
所以我们只要把设置临时环境变量的指令写入到这个文件中就可以了。

Windows 系统

在 Powershell 中设置临时的环境变量

和Linux相似，也可以在命令行中暂时的使环境变量生效

$env:GOPROXY = 'https://mirrors.aliyun.com/goproxy/'

在 CMD 中设置临时的环境变量

CMD中使用set命令就可以设置临时环境变量了

set GOPROXY=https://mirrors.aliyun.com/goproxy/