README
¶
web
web 是一个比较完整的 API 开发框架，相对于简单的路由，提供了更多的便利功能。
如果你只是需要一个简单的路由工具，那么你可以移步到 mux。
// main.go
func main() {
web.Classic("./appconfig/web.yaml")
web.NewMessages(map[int]string{...})
// 注册模块信息
m1.Init()
m2.Init()
web.Fatal(2, web.Serve())
}
// modules/m1/module.go
func Init() {
web.NewModule("m1", "模块描述信息").
GetFunc("/admins", getAdmins).
GetFunc("/groups", getGroups)
}
// modules/m2/module.go
func Init() {
web.NewModule("m2", "模块描述信息", "m1").
GetFunc("/admins", getAdmins).
GetFunc("/groups", getGroups)
}
项目结构
这只是推荐的目录结构，但不是必须按照此来。
+----- common 一些公用的包
|
+----- modules 各个模块的代码
| |
| +----- module1
| |
| +----- module2
|
+----- cmd
| |
| +----- main.go
| |
| |----- appconfig 配置文存放路径
| |
| +----- web.yaml 框架本身的配置文件
| |
| +----- logs.xml 日志配置文件
|
项目主要代码都在 modules 下的各个模块里，每一个模块需要包含一个初始化函数，
用于向框架注册当前模块的一些主要信息。通过 web.NewModule 注册模块：
m := web.NewModule("test", "测试模块")
m.AddInit(func()error {
// TODO 此处可以添加初始化模块的相关代码
return nil
}, "初始化函数描述")
m.AddService(func(ctx context.Context)error {
// TODO 此处添加服务代码
}, "服务描述")
配置文件
通过 web.Classic() 函数，可以在初始化时指定配置文件，文件格式可以是 XML、JSON 和 YAML。用户也可以自行添加新的格式支持。
以下是该文件的所有配置项：
| 名称 | 类型 | 描述 |
|---|---|---|
| debug | bool | 是否启用调试模式 |
| domain | string | 项目的域名，若存在 allowedDomains 同时会加入到 allowedDomains 字段中 |
| root | string | 项目的根路径，比如 /blog |
| plugins | string | 指定需要加载的插件，可以使用 glob 模式，仅支持部分系统，具体可见 https://golang.org/pkg/plugin/ |
| https | bool | 是否启用 HTTPS |
| certFile | string | 当启用 HTTPS 时的 cert 文件 |
| keyFile | string | 当启用 HTTPS 时的 key 文件 |
| port | int | 监听的端口号 |
| headers | object | 输出的报头，键名为报头名称，键值为对应的值 |
| static | object | 静态内容，键名为 URL 地址，键值为对应的文件夹 |
| disableOptions | bool | 是否禁用 OPTIONS 请求方法 |
| disableHead | bool | 是否禁用自动生成 HEAD 请求方法 |
| allowedDomains | array | 限定访问域名，可以是多个，若不指定，表示不限定 |
| readTimeout | string | 与 http.Server.ReadTimeout 相同 |
| writeTimeout | string | 与 http.Server.WriteTimeout 相同 |
| idleTimeout | string | 与 http.Server.IdleTimeout 相同 |
| maxHeaderBytes | int | 与 http.Server.MaxHeaderBytes 相同 |
| readHeaderTimeout | string | 与 http.Server.ReadHeaderTimeout 相同 |
| compress | array | 指定可以使用 accept-encoding 输出的 mimetype 值 |
| shutdownTimeout | string | 关闭服务的等待时间 |
| url | string | 网站首页地址，一般由 domain、root 和 port 自动拼成，但也有可能存在类似于反向代理的情况，需要自行指定不同的值。 |
| timezone | string | 时区信息，名称为 IAAN 注册的名称 |
| logs | string | 指定日志配置文件名，相对于当前目录。 |
详细的介绍可以参考 /internal/webconfig/webconfig.go 文件中的描述
在 debug 模式下，会添加两个调试用的地址：/debug/pprof/ 和 /debug/vars
logs.xml 采用 logs 包的功能，具体的配置可参考其文档。
字符集
字符集用户无须任何操作，会自动根据 Content-Type 中的 charset 属性自动解析其字符集，
输出时，也会根据 Accept-Charset 报头内容，作自动转换之后再输出。以下字符集都被支持：
https://www.iana.org/assignments/character-sets/character-sets.xhtml
媒体类型
默认情况下，框架不会处理任何的 mimetype 类型的数据。需要用户通过
Mimetypes().AddMarshals() 和 Mimetypes().AddUnmarshals() 添加相关的处理函数。
添加方式如下：
Mimetypes().AddMarshals(map[string]mimetype.MarshalFunc{
"application/json": json.Marshal,
})
Mimetypes().AddUnmarshals(map[string]mimetype.UnmarshalFunc{
"application/json": json.Unmarshal,
})
之后，通过 web.NewContext() 获得的 Context 对象，会根据用户的
Accept 和 Content-Type 自动使用相应的解析和输出格式。
当然用户也可以直接构建一个 Context 对象来生成一个一次性的对象。
错误处理
框架中提供了一个统一的错误返回类型：Result，其输出格式是固定的，类似以下：
{
"code": 400001,
"message": "error message",
"detail": [
{"field": "username", "message": "不能为空"},
{"field": "password", "message": "不能为空"},
]
}
具体可参考代码文档中的有关 web.Result 的定义。
安装
go get github.com/issue9/web
同时还提供了一个辅助工具 web，可通过调用 ./build/web.sh 进行编译。
文档
版权
Documentation
¶
Overview ¶
Package web 一个微型的 RESTful API 框架。
配置文件
配置文件的映射对象在 internal/webconfig 包中，其中有各个字段的详细说明。 用户如果需要添加一些自定义的配置项，需要自行再添加其它名称的配置文件， 文件地址最好通过 web.File 来获取，这样可以和框架本身的配置文件存在同一目录下。
框架了除了本身的 web.yaml 配置文件之外，还有 logs.xml，用于定制日志的相关内容。 具体的日志相关信息，可以访问 https://github.com/issue9/logs 包。
字符集
字符集用户无须任何操作，会自动根据 `Content-Type` 中的 charset 属性自动解析其字符集， 输出时，也会根据 `Accept-Charset` 报头内容，作自动转换之后再输出。 以下字符集都被支持： https://www.iana.org/assignments/character-sets/character-sets.xhtml
媒体类型
默认情况下，框架不会处理任何的 mimetype 类型的数据。需要用户通过 Mimetypes().AddMarshals() 和 Mimetypes().AddUnmarshals() 添加相关的处理函数。 添加方式如下：
Mimetypes().AddMarshals(map[string]mimetype.MarshalFunc{
"application/json": json.Marshal,
})
Mimetypes().AddUnmarshals(map[string]mimetype.UnmarshalFunc{
"application/json": json.Unmarshal,
})
之后，通过 web.NewContext() 获得的 context 对象，会根据用户的 Accept 和 Content-Type 自动使用相应的解析和输出格式。
当然用户也可以直接构建一个 context.Context 对象来生成一个一次性的对象。
返回结果
context 包下的 Result 表示在出错时的输出内容。在使用前，用户需要调用 web.NewMessages() 添加各类错误代码。
模块
用户可以把功能相对独立的内容当作一个模块进行封装。框架本身提供了 web.NewModule() 对模块进行了依赖管理。用户可以在 web.NewModule() 返回对象中， 对模块进行初始化和路由项的添加。所有模块会在 web.Init() 中进行初始化。
Index ¶
- Constants
- func AddCompresses(m map[string]compress.WriterFunc) error
- func AddMessages(status int, messages map[int]string)
- func AddMiddlewares(m middleware.Middleware)
- func App() *app.App
- func CRITICAL() *log.Logger
- func Classic(path string, get app.GetResultFunc) error
- func Close() error
- func Critical(v ...interface{})
- func Criticalf(format string, v ...interface{})
- func DEBUG() *log.Logger
- func Debug(v ...interface{})
- func Debugf(format string, v ...interface{})
- func ERROR() *log.Logger
- func Error(v ...interface{})
- func ErrorHandlers() *errorhandler.ErrorHandler
- func Errorf(format string, v ...interface{})
- func Fatal(code int, v ...interface{})
- func Fatalf(code int, format string, v ...interface{})
- func File(path string) string
- func FlushLogs()
- func Grace(sig ...os.Signal)
- func INFO() *log.Logger
- func Info(v ...interface{})
- func Infof(format string, v ...interface{})
- func Init(mgr *config.Manager, configFilename string, get app.GetResultFunc) (err error)
- func InitModules(tag string) error
- func IsDebug() bool
- func Jobs() []*module.Job
- func Load(r io.Reader, typ string, v interface{}) error
- func LoadFile(path string, v interface{}) error
- func Location() *time.Location
- func Messages(p *message.Printer) map[int]string
- func Mimetypes() *mimetype.Mimetypes
- func Modules() []*module.Module
- func Mux() *mux.Mux
- func Now() time.Time
- func Panic(v ...interface{})
- func Panicf(format string, v ...interface{})
- func ParseTime(layout, value string) (time.Time, error)
- func Path(path string) string
- func Serve() error
- func Server() *http.Server
- func Services() []*module.Service
- func Shutdown() error
- func TRACE() *log.Logger
- func Tags() []string
- func Trace(v ...interface{})
- func Tracef(format string, v ...interface{})
- func URL(path string) string
- func WARN() *log.Logger
- func Warn(v ...interface{})
- func Warnf(format string, v ...interface{})
- type Context
- type Module
- type Result
- type Service
- type ServiceFunc
Constants ¶
const ( // Version 当前框架的版本 Version = "0.25.3" // MinimumGoVersion 需求的最低 Go 版本 // 修改此值，记得同时修改 .travis.yml 文件中的版本依赖以及 README.md 中的相关信息。 MinimumGoVersion = "1.11" // CoreModuleName 框架自带的模块名称 CoreModuleName = module.CoreModuleName )
Variables ¶
This section is empty.
Functions ¶
func AddCompresses ¶ added in v0.25.0
func AddCompresses(m map[string]compress.WriterFunc) error
AddCompresses 添加压缩处理函数
func AddMessages ¶ added in v0.26.0
AddMessages 添加新的错误消息代码
func AddMiddlewares ¶ added in v0.18.0
func AddMiddlewares(m middleware.Middleware)
AddMiddlewares 设置全局的中间件，可多次调用。
func CRITICAL ¶ added in v0.18.0
CRITICAL 获取 CRITICAL 级别的 log.Logger 实例，在未指定 critical 级别的日志时，该实例返回一个 nil。
func Classic ¶ added in v0.25.0
func Classic(path string, get app.GetResultFunc) error
Classic 初始化一个可运行的框架环境
path 配置文件地址，该文件所在的目录，会成为项目所有配置文件的根地址。
func Critical ¶ added in v0.18.0
func Critical(v ...interface{})
Critical 相当于 CRITICAL().Println(v...)的简写方式
func Criticalf ¶ added in v0.18.0
func Criticalf(format string, v ...interface{})
Criticalf 相当于 CRITICAL().Printf(format, v...) 的简写方式
func Debugf ¶ added in v0.18.0
func Debugf(format string, v ...interface{})
Debugf 相当于 DEBUG().Printf(format, v...) 的简写方式
func ErrorHandlers ¶ added in v0.25.3
func ErrorHandlers() *errorhandler.ErrorHandler
ErrorHandlers 错误处理功能
func Errorf ¶ added in v0.18.0
func Errorf(format string, v ...interface{})
Errorf 相当于 ERROR().Printf(format, v...) 的简写方式
func Grace ¶
Grace 指定触发 Shutdown() 的信号，若为空，则任意信号都触发。
多次调用，则每次指定的信号都会起作用，如果由传递了相同的值， 则有可能多次触发 Shutdown()。
NOTE: 传递空值，与不调用，其结果是不同的。 若是不调用，则不会处理任何信号；若是传递空值调用，则是处理任何要信号。
func Info ¶ added in v0.18.0
func Info(v ...interface{})
Info 相当于 INFO().Println(v...) 的简写方式 Info 函数默认是带换行符的，若需要不带换行符的，请使用 DEBUG().Print() 函数代替。 其它相似函数也有类型功能。
func Infof ¶ added in v0.18.0
func Infof(format string, v ...interface{})
Infof 相当于 INFO().Printf(format, v...) 的简写方式
func Panicf ¶ added in v0.18.0
func Panicf(format string, v ...interface{})
Panicf 输出错误信息，然后触发 panic。
func Tracef ¶ added in v0.18.0
func Tracef(format string, v ...interface{})
Tracef 相当于 TRACE().Printf(format, v...) 的简写方式
Types ¶
type Context ¶
Context 等同于 context.Context，方便调用者使用
func NewContext ¶
func NewContext(w http.ResponseWriter, r *http.Request) *Context
NewContext 根据当前配置，生成 context.Context 对象，若是出错则 panic
type ServiceFunc ¶ added in v0.25.3
type ServiceFunc = module.ServiceFunc
ServiceFunc 等同于 module.ServiceFunc，方便调用者使用
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package app 核心功能的实现
|
Package app 核心功能的实现 |
|
cmd
|
|
|
web
简单的辅助功能命令行工具。
|
简单的辅助功能命令行工具。 |
|
Package context 用于处理单个请求的上下文关系。
|
Package context 用于处理单个请求的上下文关系。 |
|
internal
|
|
|
cmd/command
Package command 子命令管理
|
Package command 子命令管理 |
|
cmd/create
Package create 用于创建新项目的子命令
|
Package create 用于创建新项目的子命令 |
|
cmd/version
Package version 显示版本号信息
|
Package version 显示版本号信息 |
|
cmd/watch
Package watch 提供热编译功能。
|
Package watch 提供热编译功能。 |
|
plugintest
Package plugintest 作为插件的功能测试包 NOTE: 该功能如果直接写在 module 包之下，目前版本会报错。
|
Package plugintest 作为插件的功能测试包 NOTE: 该功能如果直接写在 module 包之下，目前版本会报错。 |
|
resulttest
Package resulttest 提供了 app.Result 接口的默认实现，方便测试用。
|
Package resulttest 提供了 app.Result 接口的默认实现，方便测试用。 |
|
webconfig
Package webconfig 配置文件对应的内容。
|
Package webconfig 配置文件对应的内容。 |
|
Package mimetype 提供了对编码的支持。
|
Package mimetype 提供了对编码的支持。 |
|
form
Package form 用于处理 www-form-urlencoded 编码 func read(w http.ResponseWriter, r *http.Request) { ctx := web.New(w, r) vals := urls.Values{} !ctx.Read(vals) } func write(w http.ResponseWriter, r *http.Request) { ctx := web.New(w, r) vals := urls.Values{} vals.Add("name", "caixw") ctx.Render(http.StatusOK, vals, nil) }
|
Package form 用于处理 www-form-urlencoded 编码 func read(w http.ResponseWriter, r *http.Request) { ctx := web.New(w, r) vals := urls.Values{} !ctx.Read(vals) } func write(w http.ResponseWriter, r *http.Request) { ctx := web.New(w, r) vals := urls.Values{} vals.Add("name", "caixw") ctx.Render(http.StatusOK, vals, nil) } |
|
gob
Package gob 提供 GOB 格式的编解码
|
Package gob 提供 GOB 格式的编解码 |
|
html
Package html 提供输出 HTML 内容的 mimetype.MarshalFunc 函数。
|
Package html 提供输出 HTML 内容的 mimetype.MarshalFunc 函数。 |
|
mimetypetest
Package mimetypetest 针对文本内容的编解码实现，仅作为测试用例。
|
Package mimetypetest 针对文本内容的编解码实现，仅作为测试用例。 |
|
protobuf
Package protobuf 提供对 Google protocol buffers 的支持
|
Package protobuf 提供对 Google protocol buffers 的支持 |
|
Package module 提供模块的的相关功能。
|
Package module 提供模块的的相关功能。 |