@@ -1,4 +1,5 @@
# 快速入门
你对beego一无所知？ ， ， ， ， 安装指南 ](Install.md )
**导航 **
@@ -23,11 +24,13 @@
- [第三方应用集成 ](#-19 )
- [部署编译应用 ](#-20 )
## 最小应用
一个最小最简单的应用如下代码所示：
package main
import (
"github.com/astaxie/beego"
)
@@ -59,7 +62,7 @@
2、定义Controller， `MainController` ， ， `beego.Controller` ，这样我们的`MainController` 就拥有了`beego.Controller` 的所有方法。
3、定义RESTFul方法， ， `MainController` 已经拥有了`Get` 、`Post` 、`Delete` 、`Put` 等方法， ， `POST` 请求，那么就执行`Post` 函数。所以这里我们定义了`MainController` 的`Get` 方法用来重写继承的`Get` 函数，这样当用户`GET` 请求的时候就会执行该函数。
4、定义main函数， ，
5、Router注册路由， ， ， ， `/` 的时候，请求到`MainController` 。这里我们需要知道， ， ，
@@ -68,12 +71,13 @@
停止服务的话，请按`ctrl+c`
## 新建项目
通过如下命令创建beego项目，
bee create hello
这样就建立了一个项目hello，
.
@@ -90,10 +94,11 @@
└── views
└── index.tpl
## 开发模式
通过bee创建的项目，
我们可以通过如下的方式改变我们的模式：
beego.RunMode = "pro"
@@ -115,6 +120,7 @@
## 路由设置
路由的主要功能是实现从请求地址到实现方法， `Controller` ，所以路由是从路径到`ControllerInterface` 的过程，`ControllerInterface` 的方法有如下：
@@ -144,40 +150,42 @@
为了用户更加方便的路由设置， ， ：
- beego.Router("/api/:id([0-9]+)", &controllers.RController{})
自定义正则匹配 //匹配 /api/123 :id= 123
- beego.Router("/api/:id([0-9]+)", &controllers.RController{})
自定义正则匹配 //匹配 /api/123 :id= 123
- beego.Router("/news/:all", &controllers.RController{})
- beego.Router("/news/:all", &controllers.RController{})
全匹配方式 //匹配 /news/path/to/123.html :all= path/to/123.html
- beego.Router(\`/user/:username([\w]+)\`, &controllers.RController{})
- beego.Router(\`/user/:username([\w]+)\`, &controllers.RController{})
正则字符串匹配 //匹配 /user/astaxie :username = astaxie
- beego.Router("/download/*.*", &controllers.RController{})
- beego.Router("/download/*.*", &controllers.RController{})
*匹配方式 //匹配 /download/file/api.xml :path= file/api :ext=xml
- beego.Router("/download/ceshi/*", &controllers.RController{})
*全匹配方式 //匹配 /download/ceshi/file/api.json :splat=file/api.json
- beego.Router("/:id:int", &controllers.RController{})
int类型设置方式 //匹配 :id为int类型，
- beego.Router("/:hi:string", &controllers.RController{})
string类型设置方式 //匹配 :hi为string类型。框架帮你实现了正则([\w]+)
如何在Controller中获取，
this.Ctx.Params[":id"]
this.Ctx.Params[":username"]
this.Ctx.Params[":splat"]
this.Ctx.Params[":path"]
this.Ctx.Params[":ext"]
this.Ctx.Params[":id"]
this.Ctx.Params[":username"]
this.Ctx.Params[":splat"]
this.Ctx.Params[":path"]
this.Ctx.Params[":ext"]
## 静态文件
Go语言内部其实已经提供了`http.ServeFile` ， ， ：
beego.SetStaticPath("/static","public")
- 第一个参数是路径，
- 第二个参数是静态文件目录（相对应用所在的目录）
@@ -189,37 +197,41 @@ beego支持多个目录的静态文件注册，
设置了如上的静态目录之后，用户访问`/images/login/login.png` ，那么就会访问应用对应的目录下面的`images/login/login.png` 文件。如果是访问`/static/img/logo.png` ，那么就访问`public/img/logo.png` 文件。
## 过滤和中间件
beego支持自定义过滤中间件， ，
如下例子所示， ， ：
var FilterUser = func(w http.ResponseWriter, r *http.Request) {
if r.URL.User == nil || r.URL.User.Username() != "admin" {
http.Error(w, "", http.StatusUnauthorized)
}
if r.URL.User == nil || r.URL.User.Username() != "admin" {
http.Error(w, "", http.StatusUnauthorized)
}
}
beego.Filter(FilterUser)
beego.Filter(FilterUser)
还可以通过参数进行过滤，如果匹配参数就执行
beego.Router("/:id([0-9]+)", &admin.EditController{})
beego.FilterParam("id", func(rw http.ResponseWriter, r *http.Request) {
dosomething()
dosomething()
})
当然你还可以通过前缀过滤
beego.FilterPrefixPath("/admin", func(rw http.ResponseWriter, r *http.Request) {
dosomething()
dosomething()
})
## 控制器设计
基于beego的Controller设计， `beego.Controller` 就可以了，如下所示：
type xxxController struct {
beego.Controller
beego.Controller
}
`beego.Controller` 实现了接口`beego.ControllerInterface` ， `beego.ControllerInterface` 定义了如下函数：
@@ -227,15 +239,15 @@ beego支持自定义过滤中间件， ，
- Init(ct *Context, cn string)
这个函数主要初始化了Context、相应的Controller名称， ，
- Prepare()
这个函数主要是为了用户扩展用的， ，
- Get()
如果用户请求的HTTP Method是GET, 那么就执行该函数， ，
- Post()
如果用户请求的HTTP Method是POST, 那么就执行该函数， ，
@@ -271,60 +283,71 @@ beego支持自定义过滤中间件， ，
所以通过子struct的方法重写， ， ：
type AddController struct {
beego.Controller
beego.Controller
}
func (this *AddController) Prepare() {
}
func (this *AddController) Get() {
this.Data["content"] ="value"
this.Layout = "admin/layout.html"
this.TplNames = "admin/add.tpl"
}
func (this *AddController) Post() {
pkgname := this.GetString("pkgname")
content := this.GetString("content")
pk := models.GetCruPkg(pkgname)
if pk.Id == 0 {
var pp models.PkgEntity
pp.Pid = 0
pp.Pathname = pkgname
pp.Intro = pkgname
models.InsertPkg(pp)
pk = models.GetCruPkg(pkgname)
}
var at models.Article
at.Pkgid = pk.Id
at.Content = content
models.InsertArticle(at)
this.Ctx.Redirect(302, "/admin/index")
}
func (this *AddController) Prepare() {
}
func (this *AddController) Get() {
this.Data["content"] = "value"
this.Layout = "admin/layout.html"
this.TplNames = "admin/add.tpl"
}
func (this *AddController) Post() {
pkgname := this.GetString("pkgname")
content := this.GetString("content")
pk := models.GetCruPkg(pkgname)
if pk.Id == 0 {
var pp models.PkgEntity
pp.Pid = 0
pp.Pathname = pkgname
pp.Intro = pkgname
models.InsertPkg(pp)
pk = models.GetCruPkg(pkgname)
}
var at models.Article
at.Pkgid = pk.Id
at.Content = content
models.InsertArticle(at)
this.Ctx.Redirect(302, "/admin/index")
}
## 模板处理
### 模板目录
beego中默认的模板目录是`views` ， ， ， ， ：
beego.ViewsPath = "/myviewpath"
### 自动渲染
beego中用户无需手动的调用渲染输出模板， ， ，
配置文件配置如下：
autorender = false
main.go文件中设置如下：
beego.AutoRender = false
### 模板数据
模板中的数据是通过在Controller中`this.Data` 获取的，所以如果你想在模板中获取内容`{{.Content}}` ,那么你需要在Controller中如下设置：
this.Data["Context"] = "value"
### 模板名称
beego采用了Go语言内置的模板引擎， ， ， 模板教程 ](https://github.com/astaxie/build-web-application-with-golang/blob/master/ebook/07.4.md )。
用户通过在Controller的对应方法中设置相应的模板名称， ， ， ：
@@ -341,16 +364,18 @@ beego采用了Go语言内置的模板引擎，
也就是你对应的Controller名字+请求方法名.模板后缀， `AddController` ，请求方法是`POST` ，默认的文件后缀是`tpl` ，那么就会默认请求`/viewpath/AddController/POST.tpl` 文件。
### layout设计
beego支持layout设计， ， ， ， ：
this.Layout = "admin/layout.html"
this.TplNames = "admin/add.tpl"
在layout.html中你必须设置如下的变量：
{{.LayoutContent}}
beego就会首先解析TplNames指定的文件， ，
目前采用首先把目录下所有的文件进行缓存， ：
@@ -359,12 +384,14 @@ beego就会首先解析TplNames指定的文件，
处理逻辑
{{template "footer.html"}}
### 模板函数
beego支持用户定义模板函数， `beego.Run()` 调用之前，设置如下：
func hello(in string)(out string){
out = in + "world"
return
out = in + "world"
return
}
beego.AddFuncMap("hi",hello)
@@ -375,35 +402,45 @@ beego支持用户定义模板函数，
目前beego内置的模板函数有如下：
* markdown
* markdown
实现了把markdown文本转化为html信息，
* dateformat
* dateformat
实现了时间的格式化，返回字符串，使用方法{{dateformat .Time "2006-01-02T15:04:05Z07:00"}}
* date
* date
实现了类似PHP的date函数， ，
* compare
* compare
实现了比较两个对象的比较， ， ，
* substr
* substr
实现了字符串的截取，支持中文截取的完美截取，使用方法{{substr .Str 0 30}}
* html2str
* html2str
实现了把html转化为字符串， ， ，
* str2html
* str2html
实现了把相应的字符串当作HTML来输出， ，
* htmlquote
* htmlquote
实现了基本的html字符转义，
* htmlunquote
* htmlunquote
实现了基本的反转移字符，使用方法{{htmlunquote .unquote}}
## request处理
我们经常需要获取用户传递的数据， ， ，
- GetString(key string) string
@@ -425,16 +462,18 @@ beego支持用户定义模板函数，
func (this *MainController) Post() {
id := this.Input().Get("id")
intid, err := strconv.Atoi(id)
}
}
更多其他的request的信息， `this.Ctx.Request` 获取信息，关于该对象的属性和方法参考手册[Request ](http://golang.org/pkg/net/http/#Request )
### 文件上传
在beego中你可以很容易的处理文件上传， `enctype="multipart/form-data"` ，否者你的浏览器不会传输你的上传文件。
文件上传之后一般是放在系统的内存里面， ， ， ，
beego.MaxMemory = 1<<22
beego.MaxMemory = 1<<22
或者在配置文件中通过如下设置
@@ -445,42 +484,46 @@ beego提供了两个很方便的方法来处理文件上传：
- GetFile(key string) (multipart.File, *multipart.FileHeader, error)
该方法主要用于用户读取表单中的文件名`the_file` ，然后返回相应的信息，用户根据这些变量来处理文件上传：过滤、保存文件等。
- SaveToFile(fromfile, tofile string) error
该方法是在GetFile的基础上实现了快速保存的功能
保存的代码例子如下：
func (this *MainController) Post() {
this.SaveToFile("the_file","/var/www/uploads/uploaded_file.txt"")
}
### JSON和XML输出
beego当初设计的时候就考虑了API功能的设计， ， ：
JSON数据直接输出， `content-type` 为`application/json` ：
func (this *AddController) Get() {
mystruct := { ... }
this.Data["json"] = &mystruct
this.ServeJson()
}
mystruct := { ... }
this.Data["json"] = &mystruct
this.ServeJson()
}
XML数据直接输出， `content-type` 为`application/xml` ：
func (this *AddController) Get() {
mystruct := { ... }
this.Data["xml"]=&mystruct
this.ServeXml()
}
mystruct := { ... }
this.Data["xml"]=&mystruct
this.ServeXml()
}
## 跳转和错误
我们在做Web开发的时候， ， ， `Redirect` 方法来进行跳转：
func (this *AddController) Get() {
this.Redirect("/", 302)
}
this.Redirect("/", 302)
}
如何中止此次请求并抛出异常，
@@ -494,12 +537,12 @@ XML数据直接输出， ：
this.SetSession("asta", v.(int)+1)
this.Data["Email"] = v.(int)
}
this.TplNames = "index.tpl"
this.TplNames = "index.tpl"
}
这样`this.Abort("401")` 之后的代码不会再执行，而且会默认显示给用户如下页面
beego框架默认支持404、401、403、500、503这几种错误的处理。用户可以自定义相应的错误处理， ：
@@ -514,7 +557,7 @@ beego框架默认支持404、401、403、500、503这几种错误的处理。用
beego.Errorhandler("404",page_not_found)
beego.Router("/", &controllers.MainController{})
beego.Run()
}
}
我们可以通过自定义错误页面`404.html` 来处理404错误。
@@ -526,33 +569,37 @@ beego更加人性化的还有一个设计就是支持用户自定义字符串错
data["content"] = "database is now down"
t.Execute(rw, data)
}
func main() {
beego.Errorhandler("dbError",dbError)
beego.Router("/", &controllers.MainController{})
beego.Run()
}
}
一旦在入口注册该错误处理代码，那么你可以在任何你的逻辑中遇到数据库错误调用`this.Abort("dbError")` 来进行异常页面处理。
## response处理
response可能会有集中情况：
1. 模板输出
模板输出上面模板介绍里面已经介绍，
2. 跳转
上一节介绍的跳转就是我们经常用到的页面之间的跳转
3. 字符串输出
有些时候我们只是想输出相应的一个字符串，那么我们可以通过如下的代码实现
this.Ctx.WriteString("ok")
## Sessions
beego内置了session模块， ，
beego中使用session相当方便， ：
@@ -604,21 +651,21 @@ sess对象具有如下方法：
- SessionOn
设置是否开启Session， ， ：
- SessionProvider
设置Session的引擎， ， ， ：
- SessionName
设置cookies的名字， ， ， ：
- SessionGCMaxLifetime
设置Session过期的时间， ， ：
- SessionSavePath
设置对应file、mysql、redis引擎的保存路径或者链接地址， ， ：
@@ -631,13 +678,15 @@ sess对象具有如下方法：
beego.SessionProvider = "mysql"
beego.SessionSavePath = "username:password@protocol (address)/dbname?param=value"
当SessionProvider为redis时， ， redigo ](https://github.com/garyburd/redigo )，如下所示：
beego.SessionProvider = "redis"
beego.SessionSavePath = "127.0.0.1:6379"
beego.SessionSavePath = "127.0.0.1:6379"
## Cache设置
beego内置了一个cache模块， ， ， ：
var (
@@ -649,7 +698,7 @@ beego内置了一个cache模块， ，
urllist.Every = 0 //不过期
urllist.Start()
}
func (this *ShortController) Post() {
var result ShortResult
longurl := this.Input().Get("longurl")
@@ -672,8 +721,8 @@ beego内置了一个cache模块， ，
}
this.Data["json"] = result
this.ServeJson()
}
}
上面这个例子演示了如何使用beego的Cache模块， `beego.NewBeeCache` 初始化一个对象，然后设置过期时间，开启过期检测，在业务逻辑中就可以通过如下的接口进行增删改的操作：
- Get(name string) interface{}
@@ -681,7 +730,9 @@ beego内置了一个cache模块， ，
- Delete(name string) (ok bool, err error)
- IsExist(name string) bool
## 安全的Map
我们知道在Go语言里面map是非线程安全的， atomic_maps ](http://golang.org/doc/faq#atomic_maps )。但是我们在平常的业务中经常需要用到线程安全的map， ， ：
bm := NewBeeMap()
@@ -691,16 +742,16 @@ beego内置了一个cache模块， ，
if !bm.Check("astaxie") {
t.Error("check err")
}
if v := bm.Get("astaxie"); v.(int) != 1 {
t.Error("get err")
}
bm.Delete("astaxie")
if bm.Check("astaxie") {
t.Error("delete err")
}
上面演示了如何使用线程安全的Map， ：
- Get(k interface{}) interface{}
@@ -708,7 +759,9 @@ beego内置了一个cache模块， ，
- Check(k interface{}) bool
- Delete(k interface{})
## 日志处理
beego默认有一个初始化的BeeLogger对象输出内容到stdout中， ：
beego.SetLogger(*log.Logger)
@@ -717,11 +770,13 @@ beego默认有一个初始化的BeeLogger对象输出内容到stdout中，
fd,err := os.OpenFile("/var/log/beeapp/beeapp.log", os.O_RDWR|os.O_APPEND, 0644)
if err != nil {
beego.Critical("openfile beeapp.log:", err)
return
beego.Critical("openfile beeapp.log:", err)
return
}
lg := log.New(fd, "", log.Ldate|log.Ltime)
beego.SetLogger(lg)
### 不同级别的log日志函数
* Trace(v ...interface{})
@@ -734,84 +789,96 @@ beego默认有一个初始化的BeeLogger对象输出内容到stdout中，
你可以通过下面的方式设置不同的日志分级：
beego.SetLevel(beego.LevelError)
当你代码中有很多日志输出之后， ， ， ：
beego.SetLevel(beego.LevelWarning)
这样的话就不会输出小于这个level的日志， ：
LevelTrace、LevelDebug、LevelInfo、LevelWarning、 LevelError、LevelCritical
LevelTrace、LevelDebug、LevelInfo、LevelWarning、LevelError、LevelCritical
用户可以根据不同的级别输出不同的错误信息，如下例子所示：
### Examples of log messages
- Trace
* "Entered parse function validation block"
* "Validation: entered second 'if'"
* "Dictionary 'Dict' is empty. Using default value"
- Debug
* "Web page requested: http://somesite.com Params='...'"
* "Response generated. Response size: 10000. Sending."
* "New file received. Type:PNG Size:20000"
- Info
* "Web server restarted"
* "Hourly statistics: Requested pages: 12345 Errors: 123 ..."
* "Service paused. Waiting for 'resume' call"
- Warn
* "Cache corrupted for file='test.file'. Reading from back-end"
* "Database 192.168.0.7/DB not responding. Using backup 192.168.0.8/DB"
* "No response from statistics server. Statistics not sent"
- Error
* "Internal error. Cannot process request #12345 Error:...."
* "Cannot perform login: credentials DB not responding"
- Critical
* "Critical panic received: .... Shutting down"
* "Fatal error: ... App is shutting down to prevent data corruption or loss"
### Example
func internalCalculationFunc(x, y int) (result int, err error) {
beego.Debug("calculating z. x:",x," y:",y)
beego.Debug("calculating z. x:", x, " y:", y)
z := y
switch {
case x == 3 :
case x == 3:
beego.Trace("x == 3")
panic("Failure.")
case y == 1 :
case y == 1:
beego.Trace("y == 1")
return 0, errors.New("Error!")
case y == 2 :
case y == 2:
beego.Trace("y == 2")
z = x
default :
default:
beego.Trace("default")
z += x
}
retVal := z- 3
retVal := z - 3
beego.Debug("Returning ", retVal)
return retVal, nil
}
}
func processInput(input inputData) {
defer func() {
if r := recover(); r != nil {
beego.Error("Unexpected error occurred: ", r)
outputs <- outputData{result : 0, error : true}
}
beego.Error("Unexpected error occurred: ", r)
outputs <- outputData{result: 0, error: true}
}
}()
beego.Info("Received input signal. x:",input.x," y:", input.y)
beego.Info("Received input signal. x:", input.x, " y:", input.y)
res, err := internalCalculationFunc(input.x, input.y)
res, err := internalCalculationFunc(input.x, input.y)
if err != nil {
beego.Warn("Error in calculation:", err.Error())
}
beego.Info("Returning result: ",res," error: ",err)
outputs <- outputData{result : res, error : err != nil}
beego.Info("Returning result: ", res, " error: ", err)
outputs <- outputData{result: res, error: err != nil}
}
func main() {
@@ -828,16 +895,18 @@ LevelTrace、LevelDebug、LevelInfo、LevelWarning、 LevelError、LevelCritical
for {
select {
case input := <- inputs:
processInput(input)
case <- criticalChan:
beego.Critical("Caught value from criticalChan: Go shut down.")
panic("Shut down due to critical fault.")
}
case input := <-inputs:
processInput(input)
case <-criticalChan:
beego.Critical("Caught value from criticalChan: Go shut down.")
panic("Shut down due to critical fault.")
}
}
}
## 配置管理
beego支持解析ini文件, beego默认会解析当前应用下的`conf/app.conf` 文件
通过这个文件你可以初始化很多beego的默认参数
@@ -849,7 +918,7 @@ beego支持解析ini文件, beego默认会解析当前应用下的`conf/app.conf
autorender = false
autorecover = false
viewspath = "myview"
上面这些参数会替换beego默认的一些参数。
你可以在配置文件中配置应用需要用的一些配置信息，例如下面所示的数据库信息：
@@ -858,7 +927,7 @@ beego支持解析ini文件, beego默认会解析当前应用下的`conf/app.conf
mysqlpass = "rootpass"
mysqlurls = "127.0.0.1"
mysqldb = "beego"
那么你就可以通过如下的方式获取设置的配置信息:
beego.AppConfig.String("mysqluser")
@@ -874,45 +943,47 @@ AppConfig支持如下方法
- Float(key string) (float64, error)
- String(key string) string
## 系统默认参数
beego中带有很多可配置的参数， ， ：
* BeeApp
beego默认启动的一个应用器入口， ，
* AppConfig
beego的配置文件解析之后的对象， ， `conf/app.conf` 下面所有的参数数据
* AppConfigPath
配置文件所在的路径，默认是应用程序对应的目录下的`conf/app.conf` ，用户可以修改该值配置自己的配置文件
配置文件所在的路径，默认是应用程序对应的目录下的`conf/app.conf` ，用户可以修改该值配置自己的配置文件
* HttpAddr
应用监听地址， ，
* HttpPort
应用监听端口，
* AppName
应用名称，
* RunMode
* RunMode
应用的模式， ， ， ，
* AutoRender
是否模板自动渲染， ， ， ，
* RecoverPanic
是否异常恢复， ， ， ，
* PprofOn
是否启用pprof， ， ，
@@ -922,48 +993,50 @@ beego中带有很多可配置的参数， ，
/debug/pprof/profile
/debug/pprof/symbol
关于pprof的信息， pprof ](http://golang.org/pkg/net/http/pprof/ )
* ViewsPath
模板路径，
* SessionOn
session是否开启，
* SessionProvider
session的引擎，
* SessionName
存在客户端的cookie名称，
* SessionGCMaxLifetime
session过期时间，
* SessionSavePath
session保存路径，
* UseFcgi
是否启用fastcgi，
* MaxMemory
文件上传默认内存缓存大小，默认值是`1 << 26` (64M)
* EnableGzip
是否开启gzip支持， ， ， ，
是否开启gzip支持， ， ， ，
## 第三方应用集成
beego支持第三方应用的集成， `http.Handler` ,用户可以通过如下方式进行注册路由：
beego.RouterHandler("/chat/:info(.*)", sockjshandler)
sockjshandler实现了接口`http.Handler` 。
目前在beego的example中有支持sockjs的chat例子， ：
@@ -982,7 +1055,7 @@ sockjshandler实现了接口`http.Handler`。
func chatHandler(s sockjs.Session) {
users.Add(s)
defer users.Remove(s)
for {
m := s.Receive()
if m == nil {
@@ -1013,7 +1086,9 @@ sockjshandler实现了接口`http.Handler`。
通过上面的代码很简单的实现了一个多人的聊天室。上面这个只是一个sockjs的例子， `http.Handler` ，
## 部署编译应用
Go语言的应用最后编译之后是一个二进制文件， ， ， ， ：
$ mkdir /opt/app/beepkg
@@ -1021,7 +1096,7 @@ Go语言的应用最后编译之后是一个二进制文件，
$ cp -fr views /opt/app/beepkg
$ cp -fr static /opt/app/beepkg
$ cp -fr conf /opt/app/beepkg
这样在`/opt/app/beepkg` 目录下面就会显示如下的目录结构：
.
@@ -1033,12 +1108,12 @@ Go语言的应用最后编译之后是一个二进制文件，
│ └── js
└── views
└── index.tpl
├── beepkg
├── beepkg
这样我们就已经把我们需要的应用搬到服务器了， ， ，
- Supervisord
安装和配置见[Supervisord ](Supervisord.md )
- nohup方式
Dobrosław Żybort