From ca1eaedb90886bb7b4413fd67cd438f295865256 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=B0=8F=E6=97=AD?= Date: Sun, 3 Nov 2019 18:13:52 +0800 Subject: [PATCH] fixed doc --- doc/wiki-cn/blademaster-quickstart.md | 44 +++++++++++----- doc/wiki-cn/cache-mc.md | 75 +++++++++++++++------------ doc/wiki-cn/cache-redis.md | 72 +++++++++++++------------ doc/wiki-cn/database-mysql-orm.md | 58 +++++++++++++-------- doc/wiki-cn/database-mysql.md | 68 ++++++++++++++---------- doc/wiki-cn/kratos-tool.md | 17 ++++-- doc/wiki-cn/quickstart.md | 70 ++++++++++++++----------- 7 files changed, 243 insertions(+), 161 deletions(-) diff --git a/doc/wiki-cn/blademaster-quickstart.md b/doc/wiki-cn/blademaster-quickstart.md index d3437a2c0..7e842f96f 100644 --- a/doc/wiki-cn/blademaster-quickstart.md +++ b/doc/wiki-cn/blademaster-quickstart.md @@ -4,32 +4,48 @@ ``` ├── CHANGELOG.md -├── CONTRIBUTORS.md -├── LICENSE +├── OWNERS ├── README.md +├── api +│   ├── api.bm.go +│   ├── api.pb.go +│   ├── api.proto +│   └── client.go ├── cmd │   ├── cmd │   └── main.go ├── configs │   ├── application.toml +│   ├── db.toml │   ├── grpc.toml │   ├── http.toml -│   ├── log.toml │   ├── memcache.toml -│   ├── mysql.toml │   └── redis.toml ├── go.mod ├── go.sum -└── internal - ├── dao - │   └── dao.go - ├── model - │   └── model.go - ├── server - │   └── http - │   └── http.go - └── service - └── service.go +├── internal +│   ├── dao +│   │   ├── dao.bts.go +│   │   ├── dao.go +│   │   ├── db.go +│   │   ├── mc.cache.go +│   │   ├── mc.go +│   │   └── redis.go +│   ├── di +│   │   ├── app.go +│   │   ├── wire.go +│   │   └── wire_gen.go +│   ├── model +│   │   └── model.go +│   ├── server +│   │   ├── grpc +│   │   │   └── server.go +│   │   └── http +│   │   └── server.go +│   └── service +│   └── service.go +└── test + └── docker-compose.yaml ``` # 路由 diff --git a/doc/wiki-cn/cache-mc.md b/doc/wiki-cn/cache-mc.md index 4c8efcff3..86b11bda3 100644 --- a/doc/wiki-cn/cache-mc.md +++ b/doc/wiki-cn/cache-mc.md @@ -4,32 +4,48 @@ ``` ├── CHANGELOG.md -├── CONTRIBUTORS.md -├── LICENSE +├── OWNERS ├── README.md +├── api +│   ├── api.bm.go +│   ├── api.pb.go +│   ├── api.proto +│   └── client.go ├── cmd │   ├── cmd │   └── main.go ├── configs │   ├── application.toml +│   ├── db.toml │   ├── grpc.toml │   ├── http.toml -│   ├── log.toml │   ├── memcache.toml -│   ├── mysql.toml │   └── redis.toml ├── go.mod ├── go.sum -└── internal - ├── dao - │   └── dao.go - ├── model - │   └── model.go - ├── server - │   └── http - │   └── http.go - └── service - └── service.go +├── internal +│   ├── dao +│   │   ├── dao.bts.go +│   │   ├── dao.go +│   │   ├── db.go +│   │   ├── mc.cache.go +│   │   ├── mc.go +│   │   └── redis.go +│   ├── di +│   │   ├── app.go +│   │   ├── wire.go +│   │   └── wire_gen.go +│   ├── model +│   │   └── model.go +│   ├── server +│   │   ├── grpc +│   │   │   └── server.go +│   │   └── http +│   │   └── server.go +│   └── service +│   └── service.go +└── test + └── docker-compose.yaml ``` # 开始使用 @@ -39,9 +55,8 @@ 创建项目成功后，进入项目中的configs目录，打开memcache.toml，我们可以看到： ```toml -demoExpire = "24h" -[demo] - name = "kratos-demo" +[Client] + name = "abc" proto = "tcp" addr = "127.0.0.1:11211" active = 50 @@ -49,31 +64,25 @@ demoExpire = "24h" dialTimeout = "100ms" readTimeout = "200ms" writeTimeout = "300ms" - idleTimeout = "80s" + idleTimeout = "80s" ``` 在该配置文件中我们可以配置memcache的连接方式proto、连接地址addr、连接池的闲置连接数idle、最大连接数active以及各类超时。 -这里可选添加mc的过期时间设置。 - - ## 初始化 -进入项目的internal/dao目录，打开dao.go，其中： +进入项目的internal/dao目录，打开mc.go，其中： ```go -var ( - mc struct { - Demo *memcache.Config - DemoExpire xtime.Duration - } -) +var cfg struct { + Client *memcache.Config +} checkErr(paladin.Get("memcache.toml").UnmarshalTOML(&mc)) ``` 使用paladin配置管理工具将上文中的memcache.toml中的配置解析为我们需要使用的配置。 ```go -// Dao dao. -type Dao struct { +// dao dao. +type dao struct { mc *memcache.Memcache mcExpire int32 } @@ -82,7 +91,7 @@ type Dao struct { 在dao的主结构提中定义了memcache的连接池对象和过期时间。 ```go -dao = &Dao{ +d = &dao{ // memcache mc: memcache.New(mc.Demo), mcExpire: int32(time.Duration(mc.DemoExpire) / time.Second), @@ -95,11 +104,11 @@ dao = &Dao{ ```go // Ping ping the resource. -func (d *Dao) Ping(ctx context.Context) (err error) { +func (d *dao) Ping(ctx context.Context) (err error) { return d.pingMC(ctx) } -func (d *Dao) pingMC(ctx context.Context) (err error) { +func (d *dao) pingMC(ctx context.Context) (err error) { if err = d.mc.Set(ctx, &memcache.Item{Key: "ping", Value: []byte("pong"), Expiration: 0}); err != nil { log.Error("conn.Set(PING) error(%v)", err) } diff --git a/doc/wiki-cn/cache-redis.md b/doc/wiki-cn/cache-redis.md index 8304dea0a..34ce96856 100644 --- a/doc/wiki-cn/cache-redis.md +++ b/doc/wiki-cn/cache-redis.md @@ -4,32 +4,48 @@ ``` ├── CHANGELOG.md -├── CONTRIBUTORS.md -├── LICENSE +├── OWNERS ├── README.md +├── api +│   ├── api.bm.go +│   ├── api.pb.go +│   ├── api.proto +│   └── client.go ├── cmd │   ├── cmd │   └── main.go ├── configs │   ├── application.toml +│   ├── db.toml │   ├── grpc.toml │   ├── http.toml -│   ├── log.toml │   ├── memcache.toml -│   ├── mysql.toml │   └── redis.toml ├── go.mod ├── go.sum -└── internal - ├── dao - │   └── dao.go - ├── model - │   └── model.go - ├── server - │   └── http - │   └── http.go - └── service - └── service.go +├── internal +│   ├── dao +│   │   ├── dao.bts.go +│   │   ├── dao.go +│   │   ├── db.go +│   │   ├── mc.cache.go +│   │   ├── mc.go +│   │   └── redis.go +│   ├── di +│   │   ├── app.go +│   │   ├── wire.go +│   │   └── wire_gen.go +│   ├── model +│   │   └── model.go +│   ├── server +│   │   ├── grpc +│   │   │   └── server.go +│   │   └── http +│   │   └── server.go +│   └── service +│   └── service.go +└── test + └── docker-compose.yaml ``` # 开始使用 @@ -39,9 +55,7 @@ 创建项目成功后，进入项目中的configs目录，打开redis.toml，我们可以看到： ```toml -demoExpire = "24h" - -[demo] +[Client] name = "kratos-demo" proto = "tcp" addr = "127.0.0.1:6389" @@ -55,20 +69,14 @@ demoExpire = "24h" 在该配置文件中我们可以配置redis的连接方式proto、连接地址addr、连接池的闲置连接数idle、最大连接数active以及各类超时。 -这里可选添加redis的过期时间设置。 - - ## 初始化 -进入项目的internal/dao目录，打开dao.go，其中： +进入项目的internal/dao目录，打开redis.go，其中： ```go -var ( - rc struct { - Demo *redis.Config - DemoExpire xtime.Duration - } -) +var cfg struct { + Client *memcache.Config +} checkErr(paladin.Get("redis.toml").UnmarshalTOML(&rc)) ``` 使用paladin配置管理工具将上文中的redis.toml中的配置解析为我们需要使用的配置。 @@ -84,7 +92,7 @@ type Dao struct { 在dao的主结构提中定义了redis的连接池对象和过期时间。 ```go -dao = &Dao{ +d = &dao{ // redis redis: redis.NewPool(rc.Demo), redisExpire: int32(time.Duration(rc.DemoExpire) / time.Second), @@ -97,11 +105,11 @@ dao = &Dao{ ```go // Ping ping the resource. -func (d *Dao) Ping(ctx context.Context) (err error) { +func (d *dao) Ping(ctx context.Context) (err error) { return d.pingRedis(ctx) } -func (d *Dao) pingRedis(ctx context.Context) (err error) { +func (d *dao) pingRedis(ctx context.Context) (err error) { conn := d.redis.Get(ctx) defer conn.Close() if _, err = conn.Do("SET", "ping", "pong"); err != nil { @@ -130,7 +138,7 @@ func (d *Dao) Close() { ```go // DemoIncrby . -func (d *Dao) DemoIncrby(c context.Context, pid int) (err error) { +func (d *dao) DemoIncrby(c context.Context, pid int) (err error) { cacheKey := keyDemo(pid) conn := d.redis.Get(c) defer conn.Close() @@ -149,7 +157,7 @@ kratos/pkg/cache/redis包除了支持发送单个命令，也支持批量发送 ```go // DemoIncrbys . -func (d *Dao) DemoIncrbys(c context.Context, pid int) (err error) { +func (d *dao) DemoIncrbys(c context.Context, pid int) (err error) { cacheKey := keyDemo(pid) conn := d.redis.Get(c) defer conn.Close() diff --git a/doc/wiki-cn/database-mysql-orm.md b/doc/wiki-cn/database-mysql-orm.md index 5b776034c..1e16fc771 100644 --- a/doc/wiki-cn/database-mysql-orm.md +++ b/doc/wiki-cn/database-mysql-orm.md @@ -4,32 +4,48 @@ ``` ├── CHANGELOG.md -├── CONTRIBUTORS.md -├── LICENSE +├── OWNERS ├── README.md +├── api +│   ├── api.bm.go +│   ├── api.pb.go +│   ├── api.proto +│   └── client.go ├── cmd │   ├── cmd │   └── main.go ├── configs │   ├── application.toml +│   ├── db.toml │   ├── grpc.toml │   ├── http.toml -│   ├── log.toml │   ├── memcache.toml -│   ├── mysql.toml │   └── redis.toml ├── go.mod ├── go.sum -└── internal - ├── dao - │   └── dao.go - ├── model - │   └── model.go - ├── server - │   └── http - │   └── http.go - └── service - └── service.go +├── internal +│   ├── dao +│   │   ├── dao.bts.go +│   │   ├── dao.go +│   │   ├── db.go +│   │   ├── mc.cache.go +│   │   ├── mc.go +│   │   └── redis.go +│   ├── di +│   │   ├── app.go +│   │   ├── wire.go +│   │   └── wire_gen.go +│   ├── model +│   │   └── model.go +│   ├── server +│   │   ├── grpc +│   │   │   └── server.go +│   │   └── http +│   │   └── server.go +│   └── service +│   └── service.go +└── test + └── docker-compose.yaml ``` # 开始使用 @@ -57,17 +73,15 @@ ## 初始化 -进入项目的internal/dao目录，打开dao.go，其中： +进入项目的internal/dao目录，打开db.go，其中： ```go -var ( - dc struct { - Demo *sql.Config - } -) -checkErr(paladin.Get("mysql.toml").UnmarshalTOML(&dc)) +var cfg struct { + Client *sql.Config +} +checkErr(paladin.Get("db.toml").UnmarshalTOML(&dc)) ``` -使用paladin配置管理工具将上文中的mysql.toml中的配置解析为我们需要使用mysql的相关配置。 +使用paladin配置管理工具将上文中的db.toml中的配置解析为我们需要使用db的相关配置。 # TODO：补充常用方法 diff --git a/doc/wiki-cn/database-mysql.md b/doc/wiki-cn/database-mysql.md index 3614c4e3f..2eab493bb 100644 --- a/doc/wiki-cn/database-mysql.md +++ b/doc/wiki-cn/database-mysql.md @@ -4,32 +4,48 @@ ``` ├── CHANGELOG.md -├── CONTRIBUTORS.md -├── LICENSE +├── OWNERS ├── README.md +├── api +│   ├── api.bm.go +│   ├── api.pb.go +│   ├── api.proto +│   └── client.go ├── cmd │   ├── cmd │   └── main.go ├── configs │   ├── application.toml +│   ├── db.toml │   ├── grpc.toml │   ├── http.toml -│   ├── log.toml │   ├── memcache.toml -│   ├── mysql.toml │   └── redis.toml ├── go.mod ├── go.sum -└── internal - ├── dao - │   └── dao.go - ├── model - │   └── model.go - ├── server - │   └── http - │   └── http.go - └── service - └── service.go +├── internal +│   ├── dao +│   │   ├── dao.bts.go +│   │   ├── dao.go +│   │   ├── db.go +│   │   ├── mc.cache.go +│   │   ├── mc.go +│   │   └── redis.go +│   ├── di +│   │   ├── app.go +│   │   ├── wire.go +│   │   └── wire_gen.go +│   ├── model +│   │   └── model.go +│   ├── server +│   │   ├── grpc +│   │   │   └── server.go +│   │   └── http +│   │   └── server.go +│   └── service +│   └── service.go +└── test + └── docker-compose.yaml ``` # 开始使用 @@ -57,17 +73,15 @@ ## 初始化 -进入项目的internal/dao目录，打开dao.go，其中： +进入项目的internal/dao目录，打开db.go，其中： ```go -var ( - dc struct { - Demo *sql.Config - } -) -checkErr(paladin.Get("mysql.toml").UnmarshalTOML(&dc)) +var cfg struct { + Client *sql.Config +} +checkErr(paladin.Get("db.toml").UnmarshalTOML(&dc)) ``` -使用paladin配置管理工具将上文中的mysql.toml中的配置解析为我们需要使用mysql的相关配置。 +使用paladin配置管理工具将上文中的db.toml中的配置解析为我们需要使用db的相关配置。 ```go // Dao dao. @@ -79,7 +93,7 @@ type Dao struct { 在dao的主结构提中定义了mysql的连接池对象。 ```go -dao = &Dao{ +d = &dao{ db: sql.NewMySQL(dc.Demo), } ``` @@ -90,7 +104,7 @@ dao = &Dao{ ```go // Ping ping the resource. -func (d *Dao) Ping(ctx context.Context) (err error) { +func (d *dao) Ping(ctx context.Context) (err error) { return d.db.Ping(ctx) } ``` @@ -101,7 +115,7 @@ func (d *Dao) Ping(ctx context.Context) (err error) { ```go // Close close the resource. -func (d *Dao) Close() { +func (d *dao) Close() { d.db.Close() } ``` @@ -114,7 +128,7 @@ func (d *Dao) Close() { ```go // GetDemo 用户角色 -func (d *Dao) GetDemo(c context.Context, did int64) (demo int8, err error) { +func (d *dao) GetDemo(c context.Context, did int64) (demo int8, err error) { err = d.db.QueryRow(c, _getDemoSQL, did).Scan(&demo) if err != nil && err != sql.ErrNoRows { log.Error("d.GetDemo.Query error(%v)", err) @@ -132,7 +146,7 @@ db.QueryRow方法用于返回最多一条记录的查询，在QueryRow方法后 ```go // ResourceLogs ResourceLogs. -func (d *Dao) GetDemos(c context.Context, dids []int64) (demos []int8, err error) { +func (d *dao) GetDemos(c context.Context, dids []int64) (demos []int8, err error) { rows, err := d.db.Query(c, _getDemosSQL, dids) if err != nil { log.Error("query error(%v)", err) diff --git a/doc/wiki-cn/kratos-tool.md b/doc/wiki-cn/kratos-tool.md index 68b47bc9b..312b36be4 100644 --- a/doc/wiki-cn/kratos-tool.md +++ b/doc/wiki-cn/kratos-tool.md @@ -55,10 +55,16 @@ kratos new kratos-demo kratos new kratos-demo -o YourName -d YourPath ``` -注意，`kratos new`默认是不会生成通过 protobuf 定义的`grpc`和`bm`示例代码的，如需生成请加`--proto`，如下： +注意，`kratos new`默认会生成通过 protobuf 定义的`grpc`和`bm`示例代码的，如只生成bm请加`--http`，如下： ```shell -kratos new kratos-demo -o YourName -d YourPath --proto +kratos new kratos-demo -o YourName -d YourPath --http +``` + +如只生成grpc请加`--grpc`，如下： + +```shell +kratos new kratos-demo -o YourName -d YourPath --grpc ``` > 特别注意，如果不是MacOS系统，需要自己进行手动安装protoc，用于生成的示例项目`api`目录下的`proto`文件并不会自动生成对应的`.pb.go`和`.bm.go`文件。 @@ -76,13 +82,16 @@ kratos new kratos-demo -o YourName -d YourPath --proto ``` kratos tool +protoc(已安装): 快速方便生成pb.go的protoc封装，windows、Linux请先安装protoc工具 Author(kratos) [2019/10/31] +genbts(已安装): 缓存回源逻辑代码生成器 Author(kratos) [2019/10/31] +testcli(已安装): 测试代码生成 Author(kratos) [2019/09/09] +genmc(已安装): mc缓存代码生成 Author(kratos) [2019/07/23] swagger(已安装): swagger api文档 Author(goswagger.io) [2019/05/05] -protoc(已安装): 快速方便生成pb.go和bm.go的protoc封装，windows、Linux请先安装protoc工具 Author(kratos) [2019/05/04] -kratos(已安装): Kratos工具集本体 Author(kratos) [2019/04/02] 安装工具: kratos tool install demo 执行工具: kratos tool demo 安装全部工具: kratos tool install all +全部升级: kratos tool upgrade all 详细文档： https://github.com/bilibili/kratos/blob/master/doc/wiki-cn/kratos-tool.md ``` diff --git a/doc/wiki-cn/quickstart.md b/doc/wiki-cn/quickstart.md index 19496fe60..3faed015e 100644 --- a/doc/wiki-cn/quickstart.md +++ b/doc/wiki-cn/quickstart.md @@ -11,36 +11,48 @@ kratos new kratos-demo 根据提示可以快速创建项目，如[kratos-demo](https://github.com/bilibili/kratos-demo)就是通过工具创建生成。目录结构如下： ``` -├── CHANGELOG.md # CHANGELOG -├── CONTRIBUTORS.md # CONTRIBUTORS -├── README.md # README -├── api # api目录为对外保留的proto文件及生成的pb.go文件，注：需要"--proto"参数 +├── CHANGELOG.md +├── OWNERS +├── README.md +├── api # api目录为对外保留的proto文件及生成的pb.go文件 +│   ├── api.bm.go +│   ├── api.pb.go # 通过go generate生成的pb.go文件 │   ├── api.proto -│   ├── api.pb.go # 通过go generate生成的pb.go文件 -│   └── generate.go -├── cmd # cmd目录为main所在 -│   └── main.go # main.go -├── configs # configs为配置文件目录 -│   ├── application.toml # 应用的自定义配置文件，可能是一些业务开关如：useABtest = true -│   ├── grpc.toml # grpc相关配置 -│   ├── http.toml # http相关配置 -│   ├── log.toml # log相关配置 -│   ├── memcache.toml # memcache相关配置 -│   ├── mysql.toml # mysql相关配置 -│   └── redis.toml # redis相关配置 -├── go.mod # go.mod -└── internal # internal为项目内部包，包括以下目录： - ├── dao # dao层，用于数据库、cache、MQ、依赖某业务grpc|http等资源访问 - │   └── dao.go - ├── model # model层，用于声明业务结构体 - │   └── model.go - ├── server # server层，用于初始化grpc和http server - │   └── http # http层，用于初始化http server和声明handler - │   └── http.go - │   └── grpc # grpc层，用于初始化grpc server和定义method - │   └── grpc.go - └── service # service层，用于业务逻辑处理，且为方便http和grpc共用方法，建议入参和出参保持grpc风格，且使用pb文件生成代码 - └── service.go +│   └── client.go +├── cmd +│   └── main.go # cmd目录为main所在 +├── configs # configs为配置文件目录 +│   ├── application.toml # 应用的自定义配置文件，可能是一些业务开关如：useABtest = true +│   ├── db.toml # db相关配置 +│   ├── grpc.toml # grpc相关配置 +│   ├── http.toml # http相关配置 +│   ├── memcache.toml # memcache相关配置 +│   └── redis.toml # redis相关配置 +├── go.mod +├── go.sum +└── internal # internal为项目内部包，包括以下目录： +│   ├── dao # dao层，用于数据库、cache、MQ、依赖某业务grpc|http等资源访问 +│   │   ├── dao.bts.go +│   │   ├── dao.go +│   │   ├── db.go +│   │   ├── mc.cache.go +│   │   ├── mc.go +│   │   └── redis.go +│   ├── di # 依赖注入层 采用wire静态分析依赖 +│   │   ├── app.go +│   │   ├── wire.go # wire 声明 +│   │   └── wire_gen.go # go generate 生成的代码 +│   ├── model # model层，用于声明业务结构体 +│   │   └── model.go +│   ├── server # server层，用于初始化grpc和http server +│   │   ├── grpc # grpc层，用于初始化grpc server和定义method +│   │   │   └── server.go +│   │   └── http # http层，用于初始化http server和声明handler +│   │   └── server.go +│   └── service # service层，用于业务逻辑处理，且为方便http和grpc共用方法，建议入参和出参保持grpc风格，且使用pb文件生成代码 +│   └── service.go +└── test # 测试资源层 用于存放测试相关资源数据 如docker-compose配置 数据库初始化语句等 + └── docker-compose.yaml ``` 生成后可直接运行如下：