web

README

web

web 是一个比较完整的 API 开发框架，相对于简单的路由，提供了更多的便利功能。 如果你只是需要一个简单的路由工具，那么你可以移步到 mux。

package main

import "github.com/issue9/web"

// main.go
func main() {
    srv, _ := web.NewServer("web", "1.0.0", logs.New(),&web.Options{})

    srv.NewModule(m1.Module, m2.Module) // 注册模块信息

    srv.InitModules("serve")
    srv.Serve()
}

// modules/m1/module.go
func Module(s *web.Server) error {
    m := web.NewModule("m1", "1.0.0", "模块描述信息").
    m.Tag("serve").AddRoutes(func(r*web.Router){
        r.Get("/admins", getAdmins).
            Get("/groups", getGroups)
    })
}

// modules/m2/module.go
func Module(s *web.Server) (*web.Module, error) {
    m := web.NewModule("m1", "1.0.0", "模块描述信息", "m1").
    m.Tag("serve").AddRoutes(func(r*web.Router){
        r.Get("/admins", getAdmins).
            Get("/groups", getGroups)
    })
}

模块

在 web 中项目以模块进行划分。每个模块返回一个 *web.Module 实例， 向项目注册自己的模块信息，在项目进行初始化时，会按照模块的依赖关系进行初始化。

用户可以在模块信息中添加当前模块的路由信息、服务、计划任务等， 这些功能在模块初始化时进行统一的注册初始化。

package m1

import "github.com/issue9/web"

func Module(s *web.Server) error {
    m := s.NewModule("test", "1.0.0", "测试模块")

    tag := m.Tag("serve")
    tag.AddInit(func() error {
        // TODO 此处可以添加初始化模块的相关代码
        return nil
    }, "初始化函数描述")

    tag.AddService(func(ctx context.Context) error {
        // TODO 此处添加服务代码
    }, "服务描述")

    return nil
}

插件

web 支持以插件的形式分发模块内容，只需要以 -buildmode=plugin 的形式编译每个模块， 之后将编译后的模块通过 Server.LoadPlugin() 加载即可。具体的可参考下 internal/plugintest 下的插件示例。

Go 并不是在所有的平台下都支持插件模式，支持列表可查看：https://golang.org/pkg/plugin/

字符集和文档类型

文档类型由 Server.Content 指定。 字符类型无需用户指定，https://www.iana.org/assignments/character-sets/character-sets.xhtml 中列出的字符集都能自动转换。

import "github.com/issue9/web"

srv := web.NewServer(&web.Options{})

srv.Content().Add("application/json", json.Marshal, json.Unmarshal)
srv.Content().Add("application/xml", xml.Marshal, xml.Unmarshal)

srv.Serve()

客户端只要在请求时设置 Accept 报头就可返回相应类型的数据，而 Accept-Charset 报头可设置接收的字符集。 Content-Type 则可以有向服务器指定提交内容的文档类型和字符集。

错误处理

框架提供了一种输出错误信息内容的机制，用户只需要实现 Result 接口，即可自定义输出的错误信息格式。 具体实现可参考 content.defaultResult 的实现。

版权

本项目采用 MIT 开源授权许可证，完整的授权说明可在 LICENSE 文件中找到。

Documentation

Overview

Package web 一个微型的 RESTful API 框架

Index

• Constants
• type Command
  • func (cmd *Command) Exec()
• type Context
  • func NewContext(w http.ResponseWriter, r *http.Request) *Context
• type Filter
• type HandlerFunc
• type Locale
• type Module
• type Options
• type Responser
  • func Object(status int, body interface{}, headers map[string]string) Responser
  • func Status(status int) Responser
• type Router
• type Server
  • func GetServer(r *http.Request) *Server
  • func LoadServer(name, version string, build content.BuildResultFunc, l *Locale, f fs.FS, ...) (*Server, error)
  • func NewServer(name, version string, o *Options) (*Server, error)

Constants

const Version = "0.41.0"

Version 当前框架的版本

Types

type Command

type Command struct {
	Name string // 程序名称

	Version string // 程序版本

	RegisterModules func(*Server) error // 注册模块

	// 当作服务运行的标签名
	//
	// 当标签名与此值相同时，在执行完 Server.InitModules 之后，还会执行 Server.Serve。
	//
	// 可以为空。
	ServeTags []string

	// 触发退出的信号
	//
	// 为空(nil 或是 []) 表示没有。
	Signals []os.Signal

	// 自定义命令行参数名
	CmdVersion string // 默认为 v
	CmdTag     string // 默认为 tag
	CmdFS      string // 默认为 fs

	// 命令行输出信息的通道
	//
	// 可以 os.Stdout 和 os.Stderr 选择，默认为 os.Stdout。
	Out io.Writer

	ResultBuilder content.BuildResultFunc // 默认为 nil，最终会被初始化 content.DefaultBuilder
	Locale        *serialization.Locale   // 默认情况下，能正常解析 xml、yaml 和 json
	LogsFilename  string                  // 默认为 logs.xml
	WebFilename   string                  // 默认为 web.yaml
}

Command 提供一种简单的命令行处理方式

由 Command 生成的命令行带以下三个参数：

• tag 运行的标签；
• v 显示版本号；
• fs 指定当前程序可读取的文件目录；

以上三个参数的参数名称，可在配置内容中修改。

cmd := &web.Command{
    Name: "app",
    Version: "1.0.0",
    ServeTags: []string{"serve"},
    RegisterModules: func(s *Server) error {...}
}

cmd.Exec()

func (*Command) Exec

func (cmd *Command) Exec()

Exec 执行命令行操作

type Context

type Context = server.Context

func NewContext

func NewContext(w http.ResponseWriter, r *http.Request) *Context

NewContext 构建 *Context 实例

type Filter

type Filter = server.Filter

type HandlerFunc

type HandlerFunc = server.HandlerFunc

type Locale

type Locale = serialization.Locale

type Module

type Module = server.Module

type Options

type Options = server.Options

type Responser

type Responser = server.Responser

func Object

func Object(status int, body interface{}, headers map[string]string) Responser

func Status

func Status(status int) Responser

type Router

type Router = server.Router

type Server

type Server = server.Server

func GetServer

func GetServer(r *http.Request) *Server

GetServer 从请求中获取 *Server 实例

func LoadServer

func LoadServer(name, version string, build content.BuildResultFunc, l *Locale, f fs.FS, logs, web string) (*Server, error)

LoadServer 从配置文件加载并实例化 Server 对象

locale 指定了用于加载本地化的方法，同时其关联的 serialization.Files 也用于加载配置文件； logs 和 web 用于指定日志和项目的配置文件，根据扩展由 serialization.Files 负责在 f 查找文件加载；

func NewServer

func NewServer(name, version string, o *Options) (*Server, error)

NewServer 返回 *Server 实例