README
¶
GMC Ctx 模块
简介
GMC Ctx（Context）模块提供 HTTP 请求上下文，封装了请求和响应操作，是 Web 和 API 开发的核心组件。
功能特性
- 请求处理：获取请求参数、headers、cookies 等
- 响应输出：支持 JSON、XML、HTML、文件等多种响应格式
- 会话管理：集成会话支持
- 模板渲染：集成模板引擎
- 文件上传：处理文件上传
- 国际化：集成 i18n 支持
- 元数据存储：存储请求级别的临时数据
- 分页支持：内置分页工具
快速开始
获取请求参数
func Handler(ctx gcore.Ctx) {
// GET 参数
name := ctx.Query("name", "default")
// POST 参数
email := ctx.POST("email", "")
// 路由参数
id := ctx.Param("id")
// 所有参数（优先级：POST > GET > 路由）
value := ctx.GetParam("key")
}
输出响应
func Handler(ctx gcore.Ctx) {
// JSON 响应
ctx.WriteJSON(gcore.M{
"status": "success",
"data": []string{"item1", "item2"},
})
// 文本响应
ctx.Write("Hello World")
// HTML 响应
ctx.WriteHTML("<h1>Title</h1>")
// XML 响应
ctx.WriteXML(data)
// 文件下载
ctx.WriteFile("path/to/file.pdf", "downloaded.pdf")
}
模板渲染
func Handler(ctx gcore.Ctx) {
data := gcore.M{
"title": "My Page",
"user": "John",
}
// 渲染模板
ctx.View("template.html", data)
// 或
ctx.Template().Display("template.html", data)
}
获取请求信息
func Handler(ctx gcore.Ctx) {
// 请求方法
method := ctx.Method()
// 请求路径
path := ctx.Request().URL.Path
// Headers
userAgent := ctx.GetHeader("User-Agent")
// Cookies
value, _ := ctx.GetCookie("session_id")
// 客户端 IP
ip := ctx.ClientIP()
// 请求体
body, _ := ctx.Body()
}
文件上传
func Handler(ctx gcore.Ctx) {
// 获取上传的文件
file, header, err := ctx.GetPostFile("upload")
if err != nil {
ctx.WriteE(err)
return
}
defer file.Close()
// 保存文件
err = ctx.SaveFile(header, "./uploads/"+header.Filename)
if err != nil {
ctx.WriteE(err)
return
}
ctx.WriteJSON(gcore.M{
"status": "success",
"filename": header.Filename,
})
}
会话操作
func Handler(ctx gcore.Ctx) {
sess := ctx.Session()
// 设置会话
sess.Set("user_id", 123)
// 获取会话
userID := sess.Get("user_id")
// 删除会话
sess.Delete("temp_key")
// 销毁会话
sess.Destroy()
}
API 参考
请求方法
Request() *http.Request：获取原始请求Response() http.ResponseWriter：获取原始响应Method() string：获取请求方法Query(key, defaultValue) string：获取 GET 参数POST(key, defaultValue) string：获取 POST 参数Param(key) string：获取路由参数GetParam(key) string：获取参数（POST > GET > 路由）Body() ([]byte, error)：获取请求体BodyJSON(v interface{}) error：解析 JSON 请求体GetHeader(key) string：获取 HeaderGetCookie(name) (string, error)：获取 CookieClientIP() string：获取客户端 IP
响应方法
Write(data ...interface{})：输出文本WriteE(err error)：输出错误WriteJSON(data interface{})：输出 JSONWriteJSONP(callback string, data interface{})：输出 JSONPWriteXML(data interface{})：输出 XMLWriteHTML(html string)：输出 HTMLWriteFile(filepath, downloadName)：下载文件SetHeader(key, value string)：设置响应 HeaderSetCookie(cookie *http.Cookie)：设置 CookieRedirect(url string, code int)：重定向StatusCode(code int)：设置状态码
模板和国际化
View(tpl string, data)：渲染模板Template() gcore.Template：获取模板引擎I18n() gcore.I18n：获取国际化工具Tr(lang, key, defaultMsg)：翻译文本
文件上传
GetPostFile(name) (multipart.File, *multipart.FileHeader, error)SaveFile(header, dst) error
其他
Session() gcore.Session：获取会话NewPager(count, perPage) *gutil.Pager：创建分页器Logger() gcore.Logger：获取日志记录器Config() gcore.Config：获取配置App() gcore.App：获取应用实例Metadata() *gmap.Map：获取元数据存储
使用场景
- Web 应用：处理 HTTP 请求和响应
- RESTful API：构建 API 接口
- 文件上传：处理文件上传功能
- 用户认证：基于会话的用户认证
- 多语言支持：国际化应用
最佳实践
1. 参数验证
func Handler(ctx gcore.Ctx) {
email := ctx.POST("email", "")
if email == "" {
ctx.WriteJSON(gcore.M{
"error": "email is required",
})
return
}
// 处理业务逻辑
}
2. 统一错误处理
func Handler(ctx gcore.Ctx) {
data, err := doSomething()
if err != nil {
ctx.WriteE(err)
return
}
ctx.WriteJSON(data)
}
3. 使用元数据传递数据
// 在中间件中设置
func AuthMiddleware(ctx gcore.Ctx, next func()) {
user := authenticate(ctx)
ctx.Metadata().Store("user", user)
next()
}
// 在处理器中使用
func Handler(ctx gcore.Ctx) {
user, _ := ctx.Metadata().Load("user")
// 使用 user
}
相关链接
Documentation
¶
Index ¶
- type CloudFlareIPS
- type Ctx
- func (this *Ctx) APIServer() gcore.APIServer
- func (this *Ctx) App() gcore.App
- func (this *Ctx) ClientIP() (ip string)
- func (this *Ctx) Clone() gcore.Ctx
- func (this *Ctx) CloneWithHTTP(w http.ResponseWriter, r *http.Request, ps ...gcore.Params) gcore.Ctx
- func (this *Ctx) Config() gcore.Config
- func (this *Ctx) Conn() net.Conn
- func (this *Ctx) Controller() gcore.Controller
- func (this *Ctx) ControllerMethod() string
- func (this *Ctx) Cookie(name string) string
- func (this *Ctx) FormFile(name string, maxMultipartMemory int64) (*multipart.FileHeader, error)
- func (this *Ctx) FullPath() string
- func (this *Ctx) GET(key string, Default ...string) (val string)
- func (this *Ctx) GETArray(key string, Default ...string) (val []string)
- func (this *Ctx) GETData() (data map[string]string)
- func (this *Ctx) Get(key interface{}) (value interface{}, exists bool)
- func (this *Ctx) GetParam(key string) string
- func (this *Ctx) GetPost(key string, Default ...string) (val string)
- func (this *Ctx) Header(key string) string
- func (this *Ctx) Host() (host string)
- func (this *Ctx) I18n() gcore.I18n
- func (this *Ctx) IsAJAX() bool
- func (this *Ctx) IsDELETE() bool
- func (this *Ctx) IsGET() bool
- func (this *Ctx) IsHEAD() bool
- func (this *Ctx) IsOPTIONS() bool
- func (this *Ctx) IsPATCH() bool
- func (this *Ctx) IsPOST() bool
- func (this *Ctx) IsPUT() bool
- func (this *Ctx) IsTLSRequest() bool
- func (this *Ctx) IsWebsocket() bool
- func (this *Ctx) JSON(code int, data interface{}) (err error)
- func (this *Ctx) JSONP(code int, data interface{}) (err error)
- func (this *Ctx) JSONPTo(w io.Writer, code int, data interface{}) (err error)
- func (this *Ctx) JSONTo(w io.Writer, code int, data interface{}) (err error)
- func (this *Ctx) LocalAddr() string
- func (this *Ctx) Logger() gcore.Logger
- func (this *Ctx) MultipartForm(maxMultipartMemory int64) (*multipart.Form, error)
- func (this *Ctx) MustGet(key interface{}) (v interface{})
- func (this *Ctx) NewPager(perPage int, total int64) gcore.Paginator
- func (this *Ctx) POST(key string, Default ...string) (val string)
- func (this *Ctx) POSTArray(key string, Default ...string) (val []string)
- func (this *Ctx) POSTData() (data map[string]string)
- func (this *Ctx) Param() gcore.Params
- func (this *Ctx) PrettyJSON(code int, data interface{}) (err error)
- func (this *Ctx) PrettyJSONTo(w io.Writer, code int, data interface{}) (err error)
- func (this *Ctx) Redirect(url string) (val string)
- func (this *Ctx) RemoteAddr() string
- func (this *Ctx) Request() *http.Request
- func (this *Ctx) RequestBody() ([]byte, error)
- func (this *Ctx) Response() http.ResponseWriter
- func (this *Ctx) SaveUploadedFile(file *multipart.FileHeader, dst string) error
- func (this *Ctx) Set(key interface{}, value interface{})
- func (this *Ctx) SetAPIServer(apiServer gcore.APIServer)
- func (this *Ctx) SetApp(app gcore.App)
- func (this *Ctx) SetConfig(config gcore.Config)
- func (this *Ctx) SetConn(conn net.Conn)
- func (this *Ctx) SetController(controller gcore.Controller)
- func (this *Ctx) SetControllerMethod(controllerMethod string)
- func (this *Ctx) SetCookie(name, value string, maxAge int, path, domain string, secure, httpOnly bool)
- func (this *Ctx) SetHeader(key, value string)
- func (this *Ctx) SetI18n(i18n gcore.I18n)
- func (this *Ctx) SetLocalAddr(localAddr string)
- func (this *Ctx) SetLogger(logger gcore.Logger)
- func (this *Ctx) SetParam(param gcore.Params)
- func (this *Ctx) SetRemoteAddr(remoteAddr string)
- func (this *Ctx) SetRequest(request *http.Request)
- func (this *Ctx) SetResponse(response http.ResponseWriter)
- func (this *Ctx) SetTemplate(template gcore.Template)
- func (this *Ctx) SetTimeUsed(t time.Duration)
- func (this *Ctx) SetWebServer(webServer gcore.HTTPServer)
- func (this *Ctx) Status(code int)
- func (this *Ctx) StatusCode() int
- func (this *Ctx) Stop(msg ...interface{})
- func (this *Ctx) StopJSON(code int, msg interface{})
- func (this *Ctx) Template() gcore.Template
- func (this *Ctx) TimeUsed() time.Duration
- func (this *Ctx) WebServer() gcore.HTTPServer
- func (this *Ctx) Write(data ...interface{}) (n int, err error)
- func (this *Ctx) WriteCount() int64
- func (this *Ctx) WriteE(data ...interface{}) (n int, err error)
- func (this *Ctx) WriteFile(filepath string)
- func (this *Ctx) WriteFileAttachment(filepath, filename string)
- func (this *Ctx) WriteFileFromFS(filepath string, fs http.FileSystem)
- func (this *Ctx) WriteHeader(statusCode int)
- func (this *Ctx) WriteTo(w io.Writer, data ...interface{}) (n int, err error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CloudFlareIPS ¶
type Ctx ¶
type Ctx struct {
// contains filtered or unexported fields
}
func NewCtxFromConfig ¶
func NewCtxFromConfigFile ¶
func NewCtxWithHTTP ¶
func NewCtxWithHTTP(w http.ResponseWriter, r *http.Request) *Ctx
func (*Ctx) ClientIP ¶
ClientIP acquires the real client ip, search in X-Forwarded-For, X-Real-IP, request.RemoteAddr.
func (*Ctx) CloneWithHTTP ¶
func (*Ctx) Controller ¶
func (this *Ctx) Controller() gcore.Controller
func (*Ctx) ControllerMethod ¶
func (*Ctx) Cookie ¶
Cookie returns the named cookie provided in the request or ErrNoCookie if not found. And return the named cookie is unescaped. If multiple cookies match the given name, only one cookie will be returned.
func (*Ctx) FormFile ¶
FormFile returns the first file for the provided form key. maxMultipartMemory limits the request form parser using memory byte size.
func (*Ctx) FullPath ¶
FullPath returns a matched route full path. For not found routes returns an empty string.
router.GET("/user/:id", func(c gcore.Ctx) {
c.FullPath() == "/user/:id" // true
})
func (*Ctx) Get ¶
Get returns the value for the given key, ie: (value, true). If the value does not exists it returns (nil, false)
func (*Ctx) GetParam ¶
GetParam returns the value of the URL param. It is a shortcut for c.Param().ByName(key)
router.GET("/user/:id", func(c *gcore.Ctx) {
// a GET request to /user/john
id := c.Param("id") // id == "john"
})
func (*Ctx) IsTLSRequest ¶
func (*Ctx) IsWebsocket ¶
IsWebsocket returns true if the request headers indicate that a websocket handshake is being initiated by the client.
func (*Ctx) JSON ¶
JSON serializes the given struct as JSON into the response body. It also sets the Content-Type as "application/json".
func (*Ctx) JSONP ¶
JSONP serializes the given struct as JSON into the response body. It sets the Content-Type as "application/javascript".
func (*Ctx) JSONPTo ¶
JSONPTo serializes the given struct as JSON into the io.Writer body. It sets the Content-Type as "application/javascript".
func (*Ctx) JSONTo ¶
JSONTo serializes the given struct as JSON into the io.Writer. It also sets the Content-Type as "application/json".
func (*Ctx) MultipartForm ¶
MultipartForm is the parsed multipart form, including file uploads. maxMultipartMemory limits the request form parser using memory byte size.
func (*Ctx) MustGet ¶
func (this *Ctx) MustGet(key interface{}) (v interface{})
MustGet returns the value for the given key if it exists, otherwise it panics.
func (*Ctx) POSTArray ¶
POSTArray returns a slice of strings for a given form key. The length of the slice depends on the number of params with the given key.
func (*Ctx) PrettyJSON ¶
PrettyJSON serializes the given struct as pretty JSON (indented) into the response body. It also sets the Content-Type as "application/json". WARNING: we recommend to use this only for development purposes since printing pretty JSON is more CPU and bandwidth consuming. Use Ctx.JSON() instead.
func (*Ctx) PrettyJSONTo ¶
PrettyJSONTo serializes the given struct as pretty JSON (indented) into the io.Writers. It also sets the Content-Type as "application/json". WARNING: we recommend to use this only for development purposes since printing pretty JSON is more CPU and bandwidth consuming. Use Ctx.JSON() instead.
func (*Ctx) Redirect ¶
Redirect redirects to the url, using http location header, and sets http code 302
func (*Ctx) RemoteAddr ¶
func (*Ctx) RequestBody ¶
RequestBody returns raw request body data.
func (*Ctx) Response ¶
func (this *Ctx) Response() http.ResponseWriter
func (*Ctx) SaveUploadedFile ¶
func (this *Ctx) SaveUploadedFile(file *multipart.FileHeader, dst string) error
SaveUploadedFile uploads the form file to specific dst.
func (*Ctx) Set ¶
func (this *Ctx) Set(key interface{}, value interface{})
Set is used to store a new key/value pair exclusively for this context. It also lazy initializes c.Keys if it was not used previously.
func (*Ctx) SetAPIServer ¶
func (*Ctx) SetController ¶
func (this *Ctx) SetController(controller gcore.Controller)
func (*Ctx) SetControllerMethod ¶
func (*Ctx) SetCookie ¶
func (this *Ctx) SetCookie(name, value string, maxAge int, path, domain string, secure, httpOnly bool)
SetCookie adds a Set-Cookie header to the ResponseWriter's headers. The provided cookie must have a valid Name. Invalid cookies may be silently dropped.
func (*Ctx) SetHeader ¶
SetHeader is a intelligent shortcut for ctx.Response().Header().Set(key, value). It writes a header in the response. If value == "", this method removes the header `ctx.Response().Header().Del(key)`
func (*Ctx) SetLocalAddr ¶
func (*Ctx) SetRemoteAddr ¶
func (*Ctx) SetRequest ¶
func (*Ctx) SetResponse ¶
func (this *Ctx) SetResponse(response http.ResponseWriter)
func (*Ctx) SetTemplate ¶
func (*Ctx) SetTimeUsed ¶
SetTimeUsed sets the method cost time, only for middleware2 and middleware3, do not call this.
func (*Ctx) SetWebServer ¶
func (this *Ctx) SetWebServer(webServer gcore.HTTPServer)
func (*Ctx) StatusCode ¶
StatusCode returns http code in response, if not set, default is 200.
func (*Ctx) Stop ¶
func (this *Ctx) Stop(msg ...interface{})
Stop will exit controller method or api handle function at once.
func (*Ctx) StopJSON ¶
StopJSON will exit controller method or api handle function at once. And writes the status code and a JSON body. It also sets the Content-Type as "application/json".
func (*Ctx) TimeUsed ¶
TimeUsed acquires the method cost time, only for middleware2 and middleware3.
func (*Ctx) WebServer ¶
func (this *Ctx) WebServer() gcore.HTTPServer
func (*Ctx) WriteCount ¶
WriteCount acquires outgoing bytes count by writer
func (*Ctx) WriteFile ¶
WriteFile writes the specified file into the body stream in an efficient way.
func (*Ctx) WriteFileAttachment ¶
WriteFileAttachment writes the specified file into the body stream in an efficient way On the client side, the file will typically be downloaded with the given filename
func (*Ctx) WriteFileFromFS ¶
func (this *Ctx) WriteFileFromFS(filepath string, fs http.FileSystem)
WriteFileFromFS writes the specified file from http.FileSystem into the body stream in an efficient way.
func (*Ctx) WriteHeader ¶
WriteHeader sets http code in response
Source Files