Skip to content
This repository was archived by the owner on Jun 5, 2025. It is now read-only.

Commit bfe667f

Browse files
author
dapeng
committed
update
1 parent 2a9eb66 commit bfe667f

File tree

6 files changed

+357
-17
lines changed

6 files changed

+357
-17
lines changed

‎.vscode/settings.json

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
{
22
"cSpell.words": [
33
"gonectr",
4-
"mockgen"
4+
"mockgen",
5+
"Xorm"
56
]
67
}

‎docs/references/README.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,4 +8,6 @@ next: ../goners/
88

99
## [Gone Tool](./gone-tool.md)
1010

11-
## [HTTP Injection Instructions](./http-inject.md)
11+
## [HTTP Injection Instructions](./http-inject.md)
12+
13+
## [`goner/xorm` User Guide](./xorm.md)

‎docs/references/xorm.md

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
---
2+
sidebar: auto
3+
prev: ./http-inject
4+
next: ./
5+
---
6+
7+
# `goner/xorm` User Guide
8+
9+
## Import and Loading
10+
11+
- Import the `goner` package:
12+
```go
13+
"github.com/gone-io/gone/goner"
14+
```
15+
16+
- Import database driver packages as needed:
17+
- MySQL driver:
18+
```go
19+
_ "github.com/go-sql-driver/mysql"
20+
```
21+
- SQLite3 driver:
22+
```go
23+
_ "github.com/mattn/go-sqlite3"
24+
```
25+
- PostgreSQL driver:
26+
```go
27+
_ "github.com/lib/pq"
28+
```
29+
- Oracle driver:
30+
```go
31+
_ "github.com/mattn/go-oci8"
32+
```
33+
- MSSQL driver:
34+
```go
35+
_ "github.com/denisenkom/go-mssqldb"
36+
```
37+
38+
- Load components into the `gone` framework:
39+
```go
40+
_ = goner.XormPriest(cemetery)
41+
```
42+
43+
## Configuration
44+
45+
| Option | Required | Default | Description |
46+
| :------------------------------------------- | :-----------------: | ------- | --------------------------------------------------------------------------- |
47+
| **database.cluster.enable** | No | `false` | Enables cluster mode. |
48+
| **database.driver-name** | Yes (non-cluster) | - | Database driver name. Supported: `mysql`, `sqlite3`, `postgres`, `oracle`, `mssql`. |
49+
| **database.dsn** | Yes (non-cluster) | - | Database connection string. |
50+
| **database.max-idle-count** | No | `5` | Maximum number of idle connections in the pool. |
51+
| **database.max-open** | No | `20` | Maximum number of open connections in the pool. |
52+
| **database.max-lifetime** | No | `10m` | Maximum lifetime of a connection. |
53+
| **database.show-sql** | No | `true` | Enables SQL logging. |
54+
| **database.cluster.master.driver-name** | Yes (cluster) | - | Driver name for the master database. Supported: `mysql`, `sqlite3`, `postgres`, `oracle`, `mssql`. |
55+
| **database.cluster.master.dsn** | Yes (cluster) | - | Connection string for the master database. |
56+
| **database.cluster.slaves[n].driver-name** | Yes (cluster) | - | Driver name for a slave database. Supported: `mysql`, `sqlite3`, `postgres`, `oracle`, `mssql`. |
57+
| **database.cluster.slaves[n].dsn** | Yes (cluster) | - | Connection string for a slave database. |
58+
59+
### Non-Cluster Example
60+
```ini
61+
database.driver-name=mysql
62+
database.dsn=root:123456@tcp(127.0.0.1:3306)/test?charset=utf8mb4&parseTime=True&loc=Local
63+
```
64+
65+
### Cluster Mode Example
66+
```ini
67+
database.cluster.enable=true
68+
69+
# Master database configuration
70+
database.cluster.master.driver-name=mysql
71+
database.cluster.master.dsn=root:123456@tcp(master-db-host:3306)/test?charset=utf8mb4&parseTime=True&loc=Local
72+
73+
# Slave database configuration
74+
database.cluster.slaves[0].driver-name=mysql
75+
database.cluster.slaves[0].dsn=root:123456@tcp(slave-db-0-host:3306)/test?charset=utf8mb4&parseTime=True&loc=Local
76+
77+
database.cluster.slaves[1].driver-name=mysql
78+
database.cluster.slaves[1].dsn=root:123456@tcp(slave-db-1-host:3306)/test?charset=utf8mb4&parseTime=True&loc=Local
79+
80+
database.cluster.slaves[2].driver-name=mysql
81+
database.cluster.slaves[2].dsn=root:123456@tcp(slave-db-1-host:3306)/test?charset=utf8mb4&parseTime=True&loc=Local
82+
83+
# ... additional slave databases
84+
```
85+
86+
## Injecting Database Engines in Code
87+
```go
88+
import "github.com/gone-io/gone"
89+
90+
type dbUser struct {
91+
gone.Flag
92+
db gone.XormEngine `gone:"*"` // Inject the database engine. In cluster mode, this injects the database cluster. Queries use slave databases randomly; writes use the master database.
93+
masterDb gone.XormEngine `gone:"xorm,master"` // Inject the master database. Effective in cluster mode.
94+
slaveDb0 gone.XormEngine `gone:"xorm,slave=0"` // Inject slave database 0. Effective in cluster mode.
95+
slaveDb1 gone.XormEngine `gone:"xorm,slave=1"` // Inject slave database 1. Effective in cluster mode.
96+
slaveDbs []gone.XormEngine `gone:"xorm"` // Inject a slice of slave databases. Effective in cluster mode.
97+
}
98+
99+
type Book struct {
100+
Id int64
101+
Title string
102+
}
103+
104+
func (d *dbUser) GetBookById(id int64) (book *Book, err error) {
105+
book = new(Book)
106+
has, err := d.db.Where("id=?", id).Get(book)
107+
if err != nil {
108+
return nil, gone.ToError(err)
109+
}
110+
if !has {
111+
return nil, gone.NewParameterError("book not found", 404)
112+
}
113+
return book, nil
114+
}
115+
```
116+
117+
## Multi-Database Support
118+
119+
### 1. Configuring Multiple Databases
120+
Configuration prefixes follow the pattern `database.{name}` (e.g., `database.db1`, `database.db2`).
121+
122+
| Option | Required | Default | Description |
123+
| :----------------------------------------------- | :-----------------: | ------- | ------------------------------------------------------------------------- |
124+
| **{prefix}.cluster.enable** | No | `false` | Enables cluster mode. |
125+
| **{prefix}.driver-name** | Yes (non-cluster) | - | Database driver name. Supported: `mysql`, `sqlite3`, `postgres`, `oracle`, `mssql`. |
126+
| **{prefix}.dsn** | Yes (non-cluster) | - | Database connection string. |
127+
| **{prefix}.max-idle-count** | No | `5` | Maximum number of idle connections in the pool. |
128+
| **{prefix}.max-open** | No | `20` | Maximum number of open connections in the pool. |
129+
| **{prefix}.max-lifetime** | No | `10m` | Maximum lifetime of a connection. |
130+
| **{prefix}.show-sql** | No | `true` | Enables SQL logging. |
131+
| **{prefix}.cluster.master.driver-name** | Yes (cluster) | - | Driver name for the master database. Supported: `mysql`, `sqlite3`, `postgres`, `oracle`, `mssql`. |
132+
| **{prefix}.cluster.master.dsn** | Yes (cluster) | - | Connection string for the master database. |
133+
| **{prefix}.cluster.slaves[n].driver-name** | Yes (cluster) | - | Driver name for a slave database. Supported: `mysql`, `sqlite3`, `postgres`, `oracle`, `mssql`. |
134+
| **{prefix}.cluster.slaves[n].dsn** | Yes (cluster) | - | Connection string for a slave database. |
135+
136+
### 2. Injecting Multiple Databases
137+
```go
138+
import "github.com/gone-io/gone"
139+
140+
type dbUser struct {
141+
gone.Flag
142+
143+
// Inject the database engine for `database.db1`.
144+
db1 gone.XormEngine `gone:"xorm,db=database.db1"`
145+
146+
// Inject the master database for `database.db1`.
147+
masterDb gone.XormEngine `gone:"xorm,db=database.db1,master"`
148+
149+
// Inject slave database 0 for `database.db1`.
150+
slaveDb0 gone.XormEngine `gone:"xorm,db=database.db1,slave=0"`
151+
152+
// Inject slave database 1 for `database.db1`.
153+
slaveDb1 gone.XormEngine `gone:"xorm,db=database.db1,slave=1"`
154+
155+
// Inject a slice of slave databases for `database.db1`.
156+
slaveDbs []gone.XormEngine `gone:"xorm,db=database.db1"`
157+
}
158+
```
159+
160+
## Enhancements to Xorm in Gone
161+
162+
### 1. Automatic Transactions
163+
Use the `Transaction` function to wrap database operations. A transaction is automatically started, and if an `error` is returned or a `panic` occurs, the transaction will roll back. Otherwise, it will commit automatically.
164+
165+
> **Note**: Database operations in a `Transaction` must use a `session` of type `xorm.Interface`.
166+
167+
```go
168+
type db struct {
169+
gone.Flag
170+
gone.XormEngine `gone:"gone-xorm"` // Inject the database engine.
171+
}
172+
173+
func (d *db) updateUser(user *entity.User) error {
174+
// Wrap the operation with Transaction to automatically handle commits/rollbacks.
175+
return d.Transaction(func(session xorm.Interface) error {
176+
_, err := session.ID(user.Id).Update(user)
177+
return gone.ToError(err)
178+
})
179+
}
180+
```
181+
182+
### 2. Nested Transactions
183+
Nested transactions automatically propagate into a single transaction. If one nested transaction returns an `error` or a `panic` occurs, the entire transaction will roll back.
184+
185+
```go
186+
func (d *db) updateUser(user *entity.User) error {
187+
return d.Transaction(func(session xorm.Interface) error {
188+

‎docs/zh/references/README.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,8 @@ next: ../goners/
1010

1111
## [HTTP 注入说明](./http-inject.md)
1212

13-
## [Gone对Xorm的增强](./xorm.md)
13+
## [`goner/xorm`使用说明](./xorm.md)
1414

15-
## [Redis 参考文档](./redis.md)
15+
## [`goner/redis` 使用说明](./redis.md)
1616

1717
## [`goner/zap` 使用说明](./1-zap.md)

‎docs/zh/references/redis.md

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,7 @@ prev: ./xorm
44
next: ./
55
---
66

7-
# Redis 参考文档
8-
9-
## 配置项
10-
- redis.server： redis服务器地址，例如：127.0.0.1:6379，无默认值
11-
- redis.password：redis密码，允许为空
12-
- redis.max-idle：最大空闲链接数，不配置默认为2
13-
- redis.max-active：最大活跃链接数，不配置默认为10
14-
- redis.db：使用的db，不配置默认为0
15-
- redis.cache.prefix：key前缀，如果设置了，对redis的增删改查都会拼接该前缀，拼接方式${prefix}#${key}；默认为空
7+
# `goner/redis` 使用说明
168

179
## import 和 bury
1810
- import
@@ -25,6 +17,16 @@ import "github.com/gone-io/gone/goner/redis"
2517
_ = goner.RedisPriest(cemetery)
2618
```
2719

20+
## 配置项
21+
- redis.server： redis服务器地址，例如：127.0.0.1:6379，无默认值
22+
- redis.password：redis密码，允许为空
23+
- redis.max-idle：最大空闲链接数，不配置默认为2
24+
- redis.max-active：最大活跃链接数，不配置默认为10
25+
- redis.db：使用的db，不配置默认为0
26+
- redis.cache.prefix：key前缀，如果设置了，对redis的增删改查都会拼接该前缀，拼接方式${prefix}#${key}；默认为空
27+
28+
29+
2830
## 使用分布是缓存 redis.Cache
2931
### 接口定义
3032
```go

0 commit comments

Comments
 (0)