Merge pull request #20 from go-cinch/main

[feat]add gorm gen doc

Author: piupuer

_sidebar.md

@@ -15,6 +15,7 @@
   - [配置](base/0.config.md)
   - [日志](base/1.log.md)
   - [数据库](base/2.db.md)
+  - [gorm/gen数据库映射](base/9.gorm.gen.md)
   - [缓存](base/3.cache.md)
   - [Make命令](base/4.make.md)
   - [错误管理](base/5.reason.md)

base/9.gorm.gen.md

@@ -0,0 +1,108 @@
+# Gorm Gen数据库映射
+
+项目内置gorm/gen, 数据库映射到struct, 通过工具自动生成.
+
+## 修改配置
+
+### dsn
+
+数据库连接地址.
+
+### tables
+
+需要生成的表集合.
+
+### exclude
+
+不需要生成的表集合.
+
+### association
+
+关联关系.
+
+一般是5个字段, 通过`|`分隔, `当前表名`|`关联表名`|`结构体名称`|`关系(has_one/has_many/belongs_to/many_to_many)`|`外键`
+
+!> belongs_to不常用, 具体用法参考gorm/gen官方文档
+
+#### 一对一
+
+示例, `一个用户一个角色`:
+
+```yml
+gen:
+  association:
+  - 'user|role|Role|has_one|foreignKey:RoleID'
+```
+
+#### 一对多
+
+示例, `一个问题多个选项`:
+
+```yml
+gen:
+  association:
+  - 'question|option|[]Options|has_many|foreignKey:QuestionID'
+```
+
+#### 多对多
+
+示例, `一个用户组可能有多个用户, 一个用户可能存在多个用户组`:
+
+```yml
+gen:
+  association:
+  - 'user_group|user|[]Users|many_to_many|many2many:user_user_group_relation'
+  - 'user|user_group|[]UserGroups|many_to_many|many2many:user_user_group_relation'
+```
+
+#### 特别
+
+将字段映射为指针类型:
+
+`表名`|`指针符号+字段1,指针符号+字段2,...`
+
+```yml
+gen:
+  association:
+  - 'user|*Name,*Role'
+```
+
+### field-with-string-tag
+
+将字段json增加string后缀:
+
+`表名`|`字段1,字段2,...`
+
+```yml
+gen:
+  field-with-string-tag:
+  - 'user|id,role_id'
+```
+
+生成的结构体, json tag会像这样:
+
+```go
+type User struct {
+	ID     uint64 `json:"id,string"`
+	RoleID uint64 `json:"roleId,string"`
+}
+```
+
+?> 这个功能主要是解决uint64在前端js会溢出, 通过映射为string来作为前端类型
+
+## 生成映射
+
+```bash
+cinch gen gorm
+# 🍺 Generate gorm succeeded
+# model path internal/data/query
+# query path internal/data/model
+```
+
+data目录下会新增两个目录, 其中内容包含model和query, 基于gorm/gen自动生成
+
+!> 不允许修改或新增model和query中的任何文件, 被覆盖后果自负
+
+## 源码
+
+参见[cinch/gorm](https://github.com/go-cinch/cinch/blob/dev/cmd/cinch/internal/gen/gorm/gorm.go), 有任何问题或者新需求, 欢迎提issue或pr~

started/0.init.md

@@ -136,7 +136,7 @@ git submodule add -b master --name api/game-proto https://github.com/go-cinch/ga
 # sudo apt install -y make
 make init
 
-# 5. 编译项目
+# 5. 做启动前的所有检查
 make all
 ```
 
@@ -171,23 +171,23 @@ cinch run
 ```bash
 # 启动auth
 # 如果你用的是compose/single
-export AUTH_DATA_DATABASE_DSN='root:mysqlrootpwd@tcp(127.0.0.1:3306)/auth?parseTime=True'
-export AUTH_DATA_REDIS_DSN='redis://:[email protected]:6379/0'
+export SERVICE_DATA_DATABASE_DSN='root:mysqlrootpwd@tcp(127.0.0.1:3306)/auth?parseTime=True'
+export SERVICE_DATA_REDIS_DSN='redis://:[email protected]:6379/0'
 # 其他按需修改
-export AUTH_DATA_DATABASE_DSN='root:root@tcp(127.0.0.1:3306)/auth?parseTime=True'
-export AUTH_DATA_REDIS_DSN='redis://127.0.0.1:6379/0'
+export SERVICE_DATA_DATABASE_DSN='root:root@tcp(127.0.0.1:3306)/auth?parseTime=True'
+export SERVICE_DATA_REDIS_DSN='redis://127.0.0.1:6379/0'
 cd auth
 cinch run
 
 # 启动game
 # 如果你用的是compose/single
-export GAME_DATA_DATABASE_DSN='root:mysqlrootpwd@tcp(127.0.0.1:3306)/game?parseTime=True'
-export GAME_DATA_REDIS_DSN='redis://:[email protected]:6379/0'
+export SERVICE_DATA_DATABASE_DSN='root:mysqlrootpwd@tcp(127.0.0.1:3306)/game?parseTime=True'
+export SERVICE_DATA_REDIS_DSN='redis://:[email protected]:6379/0'
 # 其他按需修改
-export GAME_DATA_DATABASE_DSN='root:root@tcp(127.0.0.1:3306)/game?parseTime=True'
-export GAME_DATA_REDIS_DSN='redis://127.0.0.1:6379/0'
+export SERVICE_DATA_DATABASE_DSN='root:root@tcp(127.0.0.1:3306)/game?parseTime=True'
+export SERVICE_DATA_REDIS_DSN='redis://127.0.0.1:6379/0'
 # 设置auth服务
-export GAME_CLIENT_AUTH='127.0.0.1:6160'
+export SERVICE_CLIENT_AUTH='127.0.0.1:6160'
 cd game
 cinch run
 ```
@@ -208,7 +208,7 @@ curl http://127.0.0.1:6060/idempotent
 game服务:
 
 ```bash
-curl http://127.0.0.1:8080/hello/world
+curl http://127.0.0.1:8080/game/list
 # 输出如下说明服务通了只是没有权限, 出现其他说明配置有误
 # {"code":401, "reason":"UNAUTHORIZED", "message":"token is missing", "metadata":{}}
 ```

started/1.first-api.md

@@ -9,6 +9,8 @@ cinch gen proto -a player
 # 🍺 Generate proto file success: api/game-proto/game.proto
 ```
 
+!> 示例中已经存在game, 直接复制改为player即可, 这里主要是演示快速生成proto
+
 ## 创建数据库
 
 ### 生成sql文件
@@ -37,7 +39,7 @@ cinch gen migrate up
 
 !> 在运行之前先清空数据库, 否则数据不一致导致生成失败
 
-### gorm反向生成data
+### 生成数据库映射
 
 ```bash
 cinch gen gorm
@@ -49,6 +51,8 @@ cinch gen gorm
 !> 建议保存gorm关系到`configs/gen.yml`, 如复杂的关联关系,
 示例[`auth/configs/gen.yml`](https://github.com/go-cinch/auth/blob/v1.0.3/configs/gen.yml)
 
+?> 参见[gorm/gen数据库映射](/base/9.gorm.gen.md)
+
 ### 生成CRUD
 
 基本包生成
@@ -104,7 +108,7 @@ func NewGameService(task *task.Task, game *biz.GameUseCase, player *biz.PlayerUs
 }
 ```
 
-## 编译
+## 启动前检查
 
 ```bash
 make all