From 62a656ec561238e47a287c8b4cca0874fce84e62 Mon Sep 17 00:00:00 2001 From: John Date: Sat, 16 Nov 2024 16:34:33 +0800 Subject: [PATCH] add api docs in quick --- ...15\347\275\256\346\226\207\344\273\266.md" | 8 +- ...41\346\225\260\346\215\256\350\241\250.md" | 44 ++++++++++ ... \347\224\237\346\210\220dao_do_entity.md" | 85 +------------------ ...45\345\217\243\345\256\232\344\271\211.md" | 6 +- ...73\350\276\221\345\256\236\347\216\260.md" | 23 ----- ...57\345\212\250\351\205\215\347\275\256.md" | 16 ---- ...57\347\224\261\346\263\250\345\206\214.md" | 73 ++++++++++++++++ 7 files changed, 127 insertions(+), 128 deletions(-) delete mode 100644 "docs/quick/\351\241\271\347\233\256\350\204\232\346\211\213\346\236\266/\346\216\245\345\217\243\345\274\200\345\217\221/Step6 - \350\267\257\347\224\261\344\270\216\345\220\257\345\212\250\351\205\215\347\275\256.md" create mode 100644 "docs/quick/\351\241\271\347\233\256\350\204\232\346\211\213\346\236\266/\346\216\245\345\217\243\345\274\200\345\217\221/Step6 - \351\205\215\347\275\256\344\270\216\350\267\257\347\224\261\346\263\250\345\206\214.md" diff --git "a/docs/docs/\346\240\270\345\277\203\347\273\204\344\273\266/\346\225\260\346\215\256\345\272\223ORM/ORM\344\275\277\347\224\250\351\205\215\347\275\256/ORM\344\275\277\347\224\250\351\205\215\347\275\256-\351\205\215\347\275\256\346\226\207\344\273\266.md" "b/docs/docs/\346\240\270\345\277\203\347\273\204\344\273\266/\346\225\260\346\215\256\345\272\223ORM/ORM\344\275\277\347\224\250\351\205\215\347\275\256/ORM\344\275\277\347\224\250\351\205\215\347\275\256-\351\205\215\347\275\256\346\226\207\344\273\266.md" index b2635dbccd2..68546a67d75 100644 --- "a/docs/docs/\346\240\270\345\277\203\347\273\204\344\273\266/\346\225\260\346\215\256\345\272\223ORM/ORM\344\275\277\347\224\250\351\205\215\347\275\256/ORM\344\275\277\347\224\250\351\205\215\347\275\256-\351\205\215\347\275\256\346\226\207\344\273\266.md" +++ "b/docs/docs/\346\240\270\345\277\203\347\273\204\344\273\266/\346\225\260\346\215\256\345\272\223ORM/ORM\344\275\277\347\224\250\351\205\215\347\275\256/ORM\344\275\277\347\224\250\351\205\215\347\275\256-\351\205\215\347\275\256\346\226\207\344\273\266.md" @@ -28,7 +28,7 @@ type:username:password@protocol(address)[/dbname][?param1=value1&...¶mN=valu 其中： - **数据库名称** 及 **特性配置** 为非必须参数，其他参数为必须参数。 -- **协议** 可选配置为： `tcp/udp/file`，常见配置为 `tcp` +- **协议** 可选配置为： `tcp/udp/unix/file`，常见配置为 `tcp` - **特性配置** 根据不同的数据库类型，由其底层实现的第三方驱动定义，具体需要参考第三方驱动官网。例如，针对 `mysql` 驱动而言，使用的第三方驱动为： [https://github.com/go-sql-driver/mysql](https://github.com/go-sql-driver/mysql) 支持的特性配置如 `multiStatements` 和 `loc` 等。 示例： @@ -39,6 +39,8 @@ database: link: "mysql:root:12345678@tcp(127.0.0.1:3306)/test" user: link: "sqlite::@file(/var/data/db.sqlite3)" + local: + link: "mysql:username:password@unix(/tmp/mysql.sock)/dbname" ``` 不同数据类型对应的 `link` 示例如下： @@ -95,7 +97,7 @@ database: timeMaintainDisabled: false # (可选)是否完全关闭时间更新特性，为true时CreatedAt/UpdatedAt/DeletedAt都将失效 ``` :::note -使用该配置方式时， **为保证数据库安全，默认底层不支持多行 `SQL` 语句执行**。为了得到更多配置项控制，请参考推荐的简化配置，同时建议您务必了解清楚简化配置项中每个连接参数的功能作用。 +使用该配置方式时， **为保证数据库安全，默认底层不支持多行 `SQL` 语句执行**。为了得到更多配置项控制，请参考推荐的`link`简化配置，并了解清楚简化配置项中每个连接参数的功能作用，以及对应驱动的官方额外配置参数。 ::: ## 集群模式 @@ -135,7 +137,7 @@ database: debug: true ``` -其中 `database.logger` 即为 `gdb` 的日志配置，当该配置不存在时，将会使用日志组件的默认配置， +其中 `database.logger` 即为 `gdb` 的日志配置，这是一项特殊的配置项，当该配置不存在时，将会使用日志组件的默认配置， 具体请参考 [日志组件-配置管理](../../../../docs/核心组件/日志组件/日志组件-配置管理.md) 章节。 :::warning 需要注意哦：由于 `ORM` 底层都是采用安全的预处理执行方式，提交到底层的 `SQL` 与参数其实是分开的，因此日志中记录的完整 `SQL` 仅作参考方便人工阅读，并不是真正提交到底层的 `SQL` 语句。 diff --git "a/docs/quick/\351\241\271\347\233\256\350\204\232\346\211\213\346\236\266/\346\216\245\345\217\243\345\274\200\345\217\221/Step1 - \350\256\276\350\256\241\346\225\260\346\215\256\350\241\250.md" "b/docs/quick/\351\241\271\347\233\256\350\204\232\346\211\213\346\236\266/\346\216\245\345\217\243\345\274\200\345\217\221/Step1 - \350\256\276\350\256\241\346\225\260\346\215\256\350\241\250.md" index 11958ae854c..a448cef7d98 100644 --- "a/docs/quick/\351\241\271\347\233\256\350\204\232\346\211\213\346\236\266/\346\216\245\345\217\243\345\274\200\345\217\221/Step1 - \350\256\276\350\256\241\346\225\260\346\215\256\350\241\250.md" +++ "b/docs/quick/\351\241\271\347\233\256\350\204\232\346\211\213\346\236\266/\346\216\245\345\217\243\345\274\200\345\217\221/Step1 - \350\256\276\350\256\241\346\225\260\346\215\256\350\241\250.md" @@ -6,6 +6,8 @@ sidebar_position: 0 --- +## 设计数据表 + 我们先定义一个数据表，以下是本章节示例会用到的数据表`SQL`文件： ```sql @@ -18,3 +20,45 @@ CREATE TABLE `user` ( ) ENGINE=InnoDB DEFAULT CHARSET=utf8; ``` +## 应用数据表 + +我们需要把这个数据表应用到`mysql`数据库中，便于后续的使用。如果你本地没有`mysql`数据库，那么这里使用`docker`运行一个吧： + +```bash +docker run -d --name mysql \ + -p 3306:3306 \ + -e MYSQL_DATABASE=test \ + -e MYSQL_ROOT_PASSWORD=12345678 \ + loads/mysql:5.7 +``` + +启动后，连接数据库，将数据表创建`sql`语句应用进去： +```text +$ mysql -h127.0.0.1 -p3306 -uroot -p +mysql: [Warning] Using a password on the command line interface can be insecure. +Enter password: +Welcome to the MySQL monitor. Commands end with ; or \g. +Your MySQL connection id is 57 +Server version: 9.0.1 Homebrew + +Copyright (c) 2000, 2024, Oracle and/or its affiliates. + +Oracle is a registered trademark of Oracle Corporation and/or its +affiliates. Other names may be trademarks of their respective +owners. + +Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. + +mysql> use test; +Database changed +mysql> CREATE TABLE `user` ( + -> `id` int(10) unsigned NOT NULL AUTO_INCREMENT COMMENT 'user id', + -> `name` varchar(45) DEFAULT NULL COMMENT 'user name', + -> `status` tinyint DEFAULT NULL COMMENT 'user status', + -> `age` tinyint unsigned DEFAULT NULL COMMENT 'user age', + -> PRIMARY KEY (`id`) + -> ) ENGINE=InnoDB DEFAULT CHARSET=utf8; +Query OK, 0 rows affected, 2 warnings (0.02 sec) + +mysql> +``` \ No newline at end of file diff --git "a/docs/quick/\351\241\271\347\233\256\350\204\232\346\211\213\346\236\266/\346\216\245\345\217\243\345\274\200\345\217\221/Step2 - \347\224\237\346\210\220dao_do_entity.md" "b/docs/quick/\351\241\271\347\233\256\350\204\232\346\211\213\346\236\266/\346\216\245\345\217\243\345\274\200\345\217\221/Step2 - \347\224\237\346\210\220dao_do_entity.md" index 5486ac2a75e..a01efaa8774 100644 --- "a/docs/quick/\351\241\271\347\233\256\350\204\232\346\211\213\346\236\266/\346\216\245\345\217\243\345\274\200\345\217\221/Step2 - \347\224\237\346\210\220dao_do_entity.md" +++ "b/docs/quick/\351\241\271\347\233\256\350\204\232\346\211\213\346\236\266/\346\216\245\345\217\243\345\274\200\345\217\221/Step2 - \347\224\237\346\210\220dao_do_entity.md" @@ -56,6 +56,8 @@ done! - `internal/dao/internal/user.go`用于封装对数据表`user`的访问。该文件自动生成了一些数据结构和方法，简化对数据表的`CURD`操作。该文件每次生成都会覆盖，由开发工具自动维护。 - `internal/dao/user.go`其实对`internal/dao/internal/user.go`的进一步封装，用于供其他模块直接调用访问。该文件开发者可以随意修改，或者扩展`dao`的能力。 +由于生成的`internal/dao/internal/user.go`文件完全由开发工具维护，那么我们只需看`internal/dao/user.go`这个生成的源码文件，后续如果有需要可以在这个文件上做功能扩展。 + ```go title="internal/dao/user.go" // ================================================================================= // This is auto-generated by GoFrame CLI tool only once. Fill this file as you wish. @@ -88,89 +90,6 @@ var ( ``` -```go title="internal/dao/internal/user.go" -// ========================================================================== -// Code generated and maintained by GoFrame CLI tool. DO NOT EDIT. -// ========================================================================== - -package internal - -import ( - "context" - - "github.com/gogf/gf/v2/database/gdb" - "github.com/gogf/gf/v2/frame/g" -) - -// UserDao is the data access object for table user. -type UserDao struct { - table string // table is the underlying table name of the DAO. - group string // group is the database configuration group name of current DAO. - columns UserColumns // columns contains all the column names of Table for convenient usage. -} - -// UserColumns defines and stores column names for table user. -type UserColumns struct { - Id string // user id - Name string // user name - Status string // user status - Age string // user age -} - -// userColumns holds the columns for table user. -var userColumns = UserColumns{ - Id: "id", - Name: "name", - Status: "status", - Age: "age", -} - -// NewUserDao creates and returns a new DAO object for table data access. -func NewUserDao() *UserDao { - return &UserDao{ - group: "default", - table: "user", - columns: userColumns, - } -} - -// DB retrieves and returns the underlying raw database management object of current DAO. -func (dao *UserDao) DB() gdb.DB { - return g.DB(dao.group) -} - -// Table returns the table name of current dao. -func (dao *UserDao) Table() string { - return dao.table -} - -// Columns returns all column names of current dao. -func (dao *UserDao) Columns() UserColumns { - return dao.columns -} - -// Group returns the configuration group name of database of current dao. -func (dao *UserDao) Group() string { - return dao.group -} - -// Ctx creates and returns the Model for current DAO, It automatically sets the context for current operation. -func (dao *UserDao) Ctx(ctx context.Context) *gdb.Model { - return dao.DB().Model(dao.table).Safe().Ctx(ctx) -} - -// Transaction wraps the transaction logic using function f. -// It rollbacks the transaction and returns the error from function f if it returns non-nil error. -// It commits the transaction and returns nil if function f returns nil. -// -// Note that, you should not Commit or Rollback the transaction in function f -// as it is automatically handled by this function. -func (dao *UserDao) Transaction(ctx context.Context, f func(ctx context.Context, tx gdb.TX) error) (err error) { - return dao.Ctx(ctx).Transaction(ctx, f) -} -``` - - ### do ```go title="internal/model/do/user.go" diff --git "a/docs/quick/\351\241\271\347\233\256\350\204\232\346\211\213\346\236\266/\346\216\245\345\217\243\345\274\200\345\217\221/Step3 - \347\274\226\345\206\231api\346\216\245\345\217\243\345\256\232\344\271\211.md" "b/docs/quick/\351\241\271\347\233\256\350\204\232\346\211\213\346\236\266/\346\216\245\345\217\243\345\274\200\345\217\221/Step3 - \347\274\226\345\206\231api\346\216\245\345\217\243\345\256\232\344\271\211.md" index b3ab2c0e5a5..9d265cddc38 100644 --- "a/docs/quick/\351\241\271\347\233\256\350\204\232\346\211\213\346\236\266/\346\216\245\345\217\243\345\274\200\345\217\221/Step3 - \347\274\226\345\206\231api\346\216\245\345\217\243\345\256\232\344\271\211.md" +++ "b/docs/quick/\351\241\271\347\233\256\350\204\232\346\211\213\346\236\266/\346\216\245\345\217\243\345\274\200\345\217\221/Step3 - \347\274\226\345\206\231api\346\216\245\345\217\243\345\256\232\344\271\211.md" @@ -59,14 +59,14 @@ type UpdateReq struct { Id int64 `v:"required" dc:"user id"` Name *string `v:"length:3,10" dc:"user name"` Age *uint `v:"between:18,200" dc:"user age"` - Status *Status `v:"enums" dc:"user status"` + Status *Status `v:"in:0,1" dc:"user status"` } type UpdateRes struct{} ``` 在这里： - 我们这里定义了一个用户状态类型`Status`，采用的是`Golang`里面约定俗成的`enums`定义方式。 -- 对`Status`参数的校验使用了`enums`校验规则，该规则将会校验传递的`Status`的值必需是我们定义的常量的两个值`StatusOK/StatusDisabled`，即`0/1`。具体的使用，后续会介绍。 +- 对`Status`参数的校验使用了`in:0,1`校验规则，该规则将会校验传递的`Status`的值必需是我们定义的常量的两个值`StatusOK/StatusDisabled`，即`0/1`。 - 接口参数我们使用了指针来接收，目的是避免类型默认值对我们修改接口的影响。举个例子，假如`Status`不定义为指针，那么它就会有默认值`0`的影响，那么在处理逻辑中，很难判断到底调用端有没有传递该参数，是否要真正修改数值为`0`。但我们使用指针后，当用户没有传递该参数时，该参数的默认值就是`nil`，处理逻辑便很好做判断。 ## 查询接口（单个） @@ -89,7 +89,7 @@ type GetOneRes struct { type GetListReq struct { g.Meta `path:"/user" method:"get" tags:"User" summary:"Get users"` Age *uint `v:"between:18,200" dc:"user age"` - Status *Status `v:"enums" dc:"user age"` + Status *Status `v:"in:0,1" dc:"user age"` } type GetListRes struct { List []*entity.User `json:"list" dc:"user list"` diff --git "a/docs/quick/\351\241\271\347\233\256\350\204\232\346\211\213\346\236\266/\346\216\245\345\217\243\345\274\200\345\217\221/Step5 - \345\256\214\346\210\220\346\216\245\345\217\243\351\200\273\350\276\221\345\256\236\347\216\260.md" "b/docs/quick/\351\241\271\347\233\256\350\204\232\346\211\213\346\236\266/\346\216\245\345\217\243\345\274\200\345\217\221/Step5 - \345\256\214\346\210\220\346\216\245\345\217\243\351\200\273\350\276\221\345\256\236\347\216\260.md" index 0cbe4679e78..11766905738 100644 --- "a/docs/quick/\351\241\271\347\233\256\350\204\232\346\211\213\346\236\266/\346\216\245\345\217\243\345\274\200\345\217\221/Step5 - \345\256\214\346\210\220\346\216\245\345\217\243\351\200\273\350\276\221\345\256\236\347\216\260.md" +++ "b/docs/quick/\351\241\271\347\233\256\350\204\232\346\211\213\346\236\266/\346\216\245\345\217\243\345\274\200\345\217\221/Step5 - \345\256\214\346\210\220\346\216\245\345\217\243\351\200\273\350\276\221\345\256\236\347\216\260.md" @@ -8,29 +8,6 @@ sidebar_position: 5 可以看到，通过项目脚手架工具，很多与项目业务逻辑无关的代码都已经预先生成好，我们只需要关注业务逻辑实现即可。我们接下来看看如何实现`CURD`逻辑吧。 -## 驱动加载 - -在实现数据库操作的`CURD`接口前，我们需要先把数据库驱动引入进来，否则咱们在运行时无法连接数据，会报错的。我们在`main.go`中加上`_ "github.com/gogf/gf/contrib/drivers/mysql/v2"`即可。 - -```go title="main.go" -package main - -import ( - _ "demo/internal/packed" - - _ "github.com/gogf/gf/contrib/drivers/mysql/v2" - - "github.com/gogf/gf/v2/os/gctx" - - "demo/internal/cmd" -) - -func main() { - cmd.Main.Run(gctx.GetInitCtx()) -} -``` - -更多关于数据库驱动的详细介绍，请参考章节 [数据库ORM](../../../docs/核心组件/数据库ORM/数据库ORM.md)。 ## 创建接口 diff --git "a/docs/quick/\351\241\271\347\233\256\350\204\232\346\211\213\346\236\266/\346\216\245\345\217\243\345\274\200\345\217\221/Step6 - \350\267\257\347\224\261\344\270\216\345\220\257\345\212\250\351\205\215\347\275\256.md" "b/docs/quick/\351\241\271\347\233\256\350\204\232\346\211\213\346\236\266/\346\216\245\345\217\243\345\274\200\345\217\221/Step6 - \350\267\257\347\224\261\344\270\216\345\220\257\345\212\250\351\205\215\347\275\256.md" deleted file mode 100644 index 19aab0bd7b0..00000000000 --- "a/docs/quick/\351\241\271\347\233\256\350\204\232\346\211\213\346\236\266/\346\216\245\345\217\243\345\274\200\345\217\221/Step6 - \350\267\257\347\224\261\344\270\216\345\220\257\345\212\250\351\205\215\347\275\256.md" +++ /dev/null @@ -1,16 +0,0 @@ ---- -slug: '/quick/scaffold-api-route-registering' -title: 'Step6 - 添加路由注册' -hide_title: true -sidebar_position: 6 ---- - - - -## 添加路由 - -添加我们新填写的`api`到路由非常简单，如下： - -![goframe路由注册](QQ_1731680426319.png) - -在分组路由的`group.Bind`方法中，通过`user.NewV1()`添加我们的路由对象即可。 \ No newline at end of file diff --git "a/docs/quick/\351\241\271\347\233\256\350\204\232\346\211\213\346\236\266/\346\216\245\345\217\243\345\274\200\345\217\221/Step6 - \351\205\215\347\275\256\344\270\216\350\267\257\347\224\261\346\263\250\345\206\214.md" "b/docs/quick/\351\241\271\347\233\256\350\204\232\346\211\213\346\236\266/\346\216\245\345\217\243\345\274\200\345\217\221/Step6 - \351\205\215\347\275\256\344\270\216\350\267\257\347\224\261\346\263\250\345\206\214.md" new file mode 100644 index 00000000000..c5fb1b5bad5 --- /dev/null +++ "b/docs/quick/\351\241\271\347\233\256\350\204\232\346\211\213\346\236\266/\346\216\245\345\217\243\345\274\200\345\217\221/Step6 - \351\205\215\347\275\256\344\270\216\350\267\257\347\224\261\346\263\250\345\206\214.md" @@ -0,0 +1,73 @@ +--- +slug: '/quick/scaffold-api-config-and-route-registering' +title: 'Step6 - 配置与路由注册' +hide_title: true +sidebar_position: 6 +--- + + +## 引入数据库驱动 + +`GoFrame`的数据库组件使用了接口化设计，接口与实现是分离的，这样能提供更好的抽象和扩展性。我们这里使用了`mysql`数据库，那么需要引入具体的`mysql`驱动实现。我们在`main.go`中加上`_ "github.com/gogf/gf/contrib/drivers/mysql/v2"`即可。 + +```go title="main.go" +package main + +import ( + _ "demo/internal/packed" + + _ "github.com/gogf/gf/contrib/drivers/mysql/v2" + + "github.com/gogf/gf/v2/os/gctx" + + "demo/internal/cmd" +) + +func main() { + cmd.Main.Run(gctx.GetInitCtx()) +} +``` +数据库的驱动，项目只需要引入这一次即可，后续都不需要做调整。 +更多关于数据库驱动的支持以及详细介绍，请参考章节 [数据库ORM](../../../docs/核心组件/数据库ORM/数据库ORM.md)。 + + +## 添加数据库配置 + +在脚手架项目模板中主要有两个配置： +- `hack/config.yaml`：工具配置，在前面的章节我们已经有过介绍。这个配置文件主要是本地开发时候使用，当`cli`脚手架工具执行时会自动读取其中的配置内容。 +- `manifest/config/config.yaml`：业务配置，主要维护业务项目的组件配置信息、业务模块配置，完全由开发者自行维护。在服务二进制文件启动时会读取该配置文件。该业务 + +默认的脚手架项目模板提供的业务配置如下： +```yaml title="manifest/config/config.yaml" +# https://goframe.org/docs/web/server-config-file-template +server: + address: ":8000" + openapiPath: "/api.json" + swaggerPath: "/swagger" + +# https://goframe.org/docs/core/glog-config +logger: + level : "all" + stdout: true + +# https://goframe.org/docs/core/gdb-config-file +database: + default: + link: "mysql:root:12345678@tcp(127.0.0.1:3306)/test" +``` + +默认提供了`3`项组件的配置，分别为： +- `server`：Web Server的配置。 +- `logger`：默认日志组件的配置。 +- `database`：数据库组件的配置。 + +每一项组件配置的注释上提供了官网文档的配置参考链接。我们这里需要修改数据库配置中的链接信息，为我们真实可用的链接信息。关于数据库的配置，请参考章节：[ORM使用配置-配置文件](../../../docs/核心组件/数据库ORM/ORM使用配置/ORM使用配置-配置文件.md) + + +## 添加路由注册 + +添加我们新填写的`api`到路由非常简单，如下： + +![goframe路由注册](QQ_1731680426319.png) + +在分组路由的`group.Bind`方法中，通过`user.NewV1()`添加我们的路由对象即可。