基于beego开发RESTfulAPI项目

go语言作为c语言同父异母的兄弟在后端服务器开发方面表现出了其惊人的天赋，出生记为高并发、多核心而生。

beego是华人谢大神借鉴tornado、sinatra 和 flask 这三个框架的精髓而设计的一个框架，该框架可以帮助人们来快速开发API、web、以及后端服务应用。

站在巨人的肩膀上，也同时作为学习go的具体实战项目，从beego开始创建一个基于前后端分离的web项目。

[帮助]

• beego官方文档
  beego案例

安装beego

beego直接通过go get安装，bee 工具是一个为了协助快速开发 beego 项目而创建的项目，通过 bee 您可以很容易的进行 beego项目的创建、热编译、开发、测试、和部署。

本项目将基于bee创建一个api工程，开发IDE采用goland（支持正版，你懂得）

$ go get -u github.com/astaxie/beego
$ go get -u github.com/beego/bee

创建API工程

创建一个xxxx.com的工程：

$bee api xxxx.com

下面运行该工程，-gendoc=true 表示每次自动化的 build 文档，-downdoc=true 就会自动的下载 swagger 文档查看器：

$bee run -gendoc=true -downdoc=true

在浏览器中输入http://localhost:8080/swagger/可以看到工程预置的user和object接口：

设计接口API

RESTful API的特点

• 基于“资源”，数据也好、服务也好，在RESTFul设计里一切都是资源。
• 无状态。一次调用一般就会返回结果，不存在类似于“打开连接-访问数据-关闭连接”这种依赖于上一次调用的情况。
• URL中通常不出现动词，只有名词
• URL语义清晰、明确
• 使用HTTP的GET、POST、DELETE、PUT来表示对于资源的增删改查
• 使用JSON不使用XML

RESTful风格的接口设计尽量遵循以下原则
参考RESTful API接口设计：

• 使用HTTP动词表示增删改查资源， GET：查询，POST：新增，PUT：更新，DELETE：删除
• 返回结果必须使用JSON
• HTTP状态码，在REST中都有特定的意义：200，201,202,204,400,401,403,500。比如401表示用户身份认证失败，403表示你验证身份通过了，但这个资源你不能操作
• 如果出现错误，返回一个错误码
• API必须有版本的概念，v1，v2，v3
• 使用Token令牌来做用户身份的校验与权限分级，而不是Cookie
• url中大小写不敏感，不要出现大写字母
• 使用 - 而不是使用 _ 做URL路径中字符串连接
• 有一份漂亮的文档

撰写API文档
API文档撰写有很多开源的工具，我使用的是showdoc（支持api接口编写和数据字典编写），支持在线编写和自己独立部署。

设计接口示例：

简要描述：

• banner

请求URL：

• /api/v1.0/banner

请求方式：

• GET

参数：

参数名	必选	类型	说明
name	是	string	banner名

banner名	参数
首页	homepage
页面二	page2
页面三	page3

返回示例

 {
   "errno": 0,
   "errmsg" "成功",
   "data": {
     "total": 1,
     "list":
	  [
		{
		"image_url": "http://",
		"title": "",
		"content": "！"
		"link": "http://"
		}
	  ]
   }
 }

返回参数说明

参数名	类型	说明
total	int	banner的总数量
image_url	string	图片地址
title	string	banner标题
content	string	banner文本

备注

• 更多返回错误代码请看首页的错误代码描述

设计数据模型

如果说接口文档是是对项目中所有功能的的梳理，是前后端开发的纽带，那么数据模型则是整个项目开发过程中的基石，数据模型设计的好坏直接关系到项目的优劣，包括可维护性、架构合理性、多模块的协作性。
1. 创建数据字典

数据库设计规范
需注意的数据库设计原则可参考

• 规则 1：弄清楚将要开发的应用程序是什么性质的（OLTP 还是 OPAP）？
• 规则 2：将你的数据按照逻辑意义分成不同的块，让事情做起来更简单
• 规则 3：不要过度使用 “规则 2”
• 规则 4：把重复、不统一的数据当成你最大的敌人来对待
• 规则 5：当心被分隔符分割的数据，它们违反了“字段不可再分”