From a420a75e461570f85f35f5ed773199606c19d046 Mon Sep 17 00:00:00 2001 From: marvin Date: Mon, 17 Jan 2022 18:09:21 +0800 Subject: [PATCH] move config description to godoc --- README.md | 56 +++--------------------------------------------- README.zh-CN.md | 57 +++---------------------------------------------- sharding.go | 44 +++++++++++++++++++++++++++++++++----- 3 files changed, 45 insertions(+), 112 deletions(-) diff --git a/README.md b/README.md index 74cc5a8..a30ffd2 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,9 @@ go get -u github.com/longbridgeapp/gorm-sharding After the database connection opened, use the sharding plugin that registered the tables which you want to shard. -The `Register` function takes a map, the key is the **original table name** and the value is a **resolver** which is composed by five configurable fields that described in [Config description](#config-description). +The `Register` function takes a map, the key is the **original table name** and the value is a **resolver** which is composed by five configurable fields. + +For config detail info, see [Godoc](https://pkg.go.dev/github.com/longbridge/gorm-sharding). ## Usage Example @@ -52,58 +54,6 @@ middleware := sharding.Register(map[string]sharding.Resolver{ db.Use(middleware) ``` -## Config description - -- [EnableFullTable](#EnableFullTable) -- [ShardingColumn](#ShardingColumn) -- [ShardingAlgorithm](#ShardingAlgorithm) -- [ShardingAlgorithmByPrimaryKey](#ShardingAlgorithmByPrimaryKey) -- [PrimaryKeyGenerate](#PrimaryKeyGenerate) - -#### EnableFullTable - -Whether to enable a full table. - -When full table enabled, sharding plugin will double write data to both main table and sharding table. - -#### ShardingColumn - -Which table column you want to used for sharding the table rows. - -For example, for a product order table, you may want to split the rows by `user_id`. - -### ShardingAlgorithm - -A function to generate the sharding table's suffix by the column value. - -It's signature is `func(columnValue interface{}) (suffix string, err error)`. - -For an example, see the [usage example](#usage-example) above. - -#### ShardingAlgorithmByPrimaryKey - -A function to generate the sharding table's suffix by the primary key. - -It's signature is `func(id int64) (suffix string)`. - -For an example, see the [usage example](#usage-example) above. - -Note, when the record contains an id field, ShardingAlgorithmByPrimaryKey will preferred than ShardingAlgorithm. - -#### PrimaryKeyGenerate - -A function to generate the primary key. - -Used only when insert and the record does not contains an id field. - -It's signature is `func(tableIdx int64) int64`. - -For an example, see the [usage example](#usage-example) above. - -We recommend you use the [keygen](https://github.com/longbridgeapp/gorm-sharding/tree/main/keygen) component, it is a distributed primary key generator. - -When use auto-increment like generator, the tableIdx argument could ignored. - ## License This project under MIT license. diff --git a/README.zh-CN.md b/README.zh-CN.md index 3faf2b7..19c80c5 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -24,7 +24,9 @@ go get -u github.com/longbridgeapp/gorm-sharding 数据库连接打开后，使用分表插件注册需要拆分的表。 -`Register` 函数接收一个 map，键是**原始表名**，值是一个 **resolver** ，由可配置的字段组成，见配置描述。 +`Register` 函数接收一个 map，键是**原始表名**，值是一个 **resolver** ，由可配置的字段组成。 + +具体配置信息见 [Godoc](https://pkg.go.dev/github.com/longbridge/gorm-sharding)。 ## 用法示例 @@ -52,59 +54,6 @@ middleware := sharding.Register(map[string]sharding.Resolver{ db.Use(middleware) ``` -## 配置描述 - -- [EnableFullTable](#EnableFullTable) -- [ShardingColumn](#ShardingColumn) -- [ShardingAlgorithm](#ShardingAlgorithm) -- [ShardingAlgorithmByPrimaryKey](#ShardingAlgorithmByPrimaryKey) -- [PrimaryKeyGenerate](#PrimaryKeyGenerate) - -#### EnableFullTable - -Whether to enable a full table. -是否开启全表。 - -开启后，分表插件将双写数据到主表和分表。 - -#### ShardingColumn - -用来分表的表字段。 - -如，对于一个订单表，你可能想用 `user_id` 拆分数据。 - -### ShardingAlgorithm - -使用列值生成分表后缀的函数。 - -签名是 `func(columnValue interface{}) (suffix string, err error)`。 - -可以参考上面的用法示例。 - -#### ShardingAlgorithmByPrimaryKey - -使用主键生成分表后缀的函数。 - -签名是 `func(id int64) (suffix string)`。 - -可以参考上面的用法示例。 - -注意，当记录包含 id 字段时，ShardingAlgorithmByPrimaryKey 优先于 ShardingAlgorithm。 - -#### PrimaryKeyGenerate - -生成主键的函数。 - -只有当插入数据并且记录不包含 id 字段时使用。 - -签名是 `func(tableIdx int64) int64`。 - -可以参考上面的用法示例。 - -推荐使用 [keygen](https://github.com/longbridgeapp/gorm-sharding/tree/main/keygen) 组件，它是一个分布式的主键生成器。 - -当使用自增类的生成器时，tableIdx 参数可以忽略。 - ## 许可证 本项目使用 MIT 许可证。 diff --git a/sharding.go b/sharding.go index 4ddfbb1..dcdaa8c 100644 --- a/sharding.go +++ b/sharding.go @@ -24,15 +24,49 @@ type Sharding struct { } type Resolver struct { - // EnableFullTable whether to enable a full table + // EnableFullTable represents whether to enable full table. + // When enabled, data will double write to both main table and sharding table. EnableFullTable bool - // ShardingColumn column name of the sharding column, for example: user_id + + // ShardingColumn specifies the table column you want to used for sharding the table rows. + // For example, for a product order table, you may want to split the rows by `user_id`. ShardingColumn string - // ShardingAlgorithm implement the sharding algorithm for generate table name suffix + + // ShardingAlgorithm specifies a function to generate the sharding + // table's suffix by the column value. + // For example, this function implements a mod sharding algorithm. + // + // func(value interface{}) (suffix string, err error) { + // if uid, ok := value.(int64);ok { + // return fmt.Sprintf("_%02d", user_id % 64), nil + // } + // return "", errors.New("invalid user_id") + // } ShardingAlgorithm func(columnValue interface{}) (suffix string, err error) - // ShardingAlgorithm sharding algorithm by primary key, if it posible. + + // ShardingAlgorithmByPrimaryKey specifies a function to generate the sharding + // table's suffix by the primary key. + // Note, when the record contains an id field, + // ShardingAlgorithmByPrimaryKey will preferred than ShardingAlgorithm. + // For example, this function use the Keygen library to generate the suffix. + // + // func(id int64) (suffix string) { + // return fmt.Sprintf("_%02d", keygen.TableIdx(id)) + // } ShardingAlgorithmByPrimaryKey func(id int64) (suffix string) - // PrimaryKeyGenerate for generate primary key + + // PrimaryKeyGenerate specifies a function to generate the primary key. + // Used only when insert and the record does not contains an id field. + // We recommend you use the + // [keygen](https://github.com/longbridgeapp/gorm-sharding/tree/main/keygen) component, + // it is a distributed primary key generator. + // When use auto-increment like generator, the tableIdx argument could ignored. + // + // For example, this function use the Keygen library to generate the primary key. + // + // func(tableIdx int64) int64 { + // return keygen.Next(tableIdx) + // } PrimaryKeyGenerate func(tableIdx int64) int64 }