Documentation ¶
Overview ¶
Package dsn implements dsn parse with struct bind
DSN 格式类似 URI, DSN 结构如下图
network:[//[username[:password]@]address[:port][,address[:port]]][/path][?query][#fragment]
与 URI 的主要区别在于 scheme 被替换为 network, host 被替换为 address 并且支持多个 address. network 与 net 包中 network 意义相同, tcp、udp、unix 等, address 支持多个使用 ',' 分割, 如果 network 为 unix 等本地 sock 协议则使用 Path, 有且只有一个
dsn 包主要提供了 Parse, Bind 和 validate 功能
Parse 解析 dsn 字符串成 DSN struct, DSN struct 与 url.URL 几乎完全一样 ¶
Bind 提供将 DSN 数据绑定到一个 struct 的功能, 通过 tag dsn:"key,[default]" 指定绑定的字段, 目前支持两种类型的数据绑定
内置变量 key:
network string tcp, udp, unix 等, 参考 net 包中的 network username string password string address string or []string address 可以绑定到 string 或者 []string, 如果为 string 则取 address 第一个
Query: 通过 query.name 可以取到 query 上的数据
数组可以通过传递多个获得 array=1&array=2&array3 -> []int `tag:"query.array"` struct 支持嵌套 foo.sub.name=hello&foo.tm=hello struct Foo { Tm string `dsn:"query.tm"` Sub struct { Name string `dsn:"query.name"` } `dsn:"query.sub"` }
默认值: 通过 dsn:"key,[default]" 默认值暂时不支持数组
忽略 Bind: 通过 dsn:"-" 忽略 Bind
自定义 Bind: 可以同时实现 encoding.TextUnmarshaler 自定义 Bind 实现
Validate: 参考 https://github.com/go-playground/validator
使用参考: example_test.go
DSN 命名规范:
没有历史遗留的情况下,尽量使用 Address, Network, Username, Password 等命名,代替之前的 Proto 和 Addr 等命名
Query 命名参考, 使用驼峰小写开头:
timeout 通用超时 dialTimeout 连接建立超时 readTimeout 读操作超时 writeTimeout 写操作超时 readsTimeout 批量读超时 writesTimeout 批量写超时
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BindTypeError ¶
BindTypeError describes a query value that was not appropriate for a value of a specific Go type.
func (*BindTypeError) Error ¶
func (e *BindTypeError) Error() string
type DSN ¶
DSN a DSN represents a parsed DSN as same as url.URL.
func Parse ¶
Parse parses rawdsn into a URL structure.
Example ¶
package main import ( "log" "github.com/HuJingwei/go-zero/pkg/conf/dsn" xtime "github.com/HuJingwei/go-zero/pkg/time" ) // Config struct type Config struct { Network string `dsn:"network" validate:"required"` Host string `dsn:"host" validate:"required"` Username string `dsn:"username" validate:"required"` Password string `dsn:"password" validate:"required"` Timeout xtime.Duration `dsn:"query.timeout,1s"` Offset int `dsn:"query.offset" validate:"gte=0"` } func main() { cfg := &Config{} d, err := dsn.Parse("tcp://root:toor@172.12.12.23:2233?timeout=10s") if err != nil { log.Fatal(err) } _, err = d.Bind(cfg) if err != nil { log.Fatal(err) } log.Printf("%v", cfg) }
Output:
func (*DSN) Bind ¶
Bind dsn to specify struct and validate use use go-playground/validator format
The bind of each struct field can be customized by the format string stored under the 'dsn' key in the struct field's tag. The format string gives the name of the field, possibly followed by a comma-separated list of options. The name may be empty in order to specify options without overriding the default field name.
A two type data you can bind to struct built-in values, use below keys to bind built-in value
username password address network
the value in query string, use query.{name} to bind value in query string
As a special case, if the field tag is "-", the field is always omitted. NOTE: that a field with name "-" can still be generated using the tag "-,".
Examples of struct field tags and their meanings:
// Field bind username Field string `dsn:"username"` // Field is ignored by this package. Field string `dsn:"-"` // Field bind value from query Field string `dsn:"query.name"`
type InvalidBindError ¶
InvalidBindError describes an invalid argument passed to DecodeQuery. (The argument to DecodeQuery must be a non-nil pointer.)
func (*InvalidBindError) Error ¶
func (e *InvalidBindError) Error() string