简单 web 服务与客户端开发

简单 web 服务与客户端开发实战个人报告

任务目标

1. 选择合适的 API，实现从接口或资源（领域）建模，到 API 设计的过程
2. 使用 API 工具，编制 API 描述文件，编译生成服务器、客户端原型
3. 使用 Github 建立一个组织，通过 API 文档，实现 客户端项目 与 RESTful 服务项目同步开发
4. 使用 API 设计工具提供 Mock 服务，两个团队独立测试 API
5. 使用 travis 测试相关模块

实验流程

这次是实现一个简单的购物车功能，用户可以通过登录网页之后浏览网页上的商品并决定是否加入其购物车或者从购物车中删除。简单回顾一下开发流程：

1. 选取goxygen脚手架进行前后端分离开发
2. 设计API并通过swaager工具生成API文档
3. 根据API文档前后端各自开发
4. 期间通过协调对API进行适当修改
5. 完成后进行测试，解决一些bug

个人报告

本人在这次团队项目中主要负责后端部分，包括API文档的生成和部分API的编写。

API文档生成

API采用REST v3风格，设置了User、Commodity、Comment、Cart四种资源和超过6个的API服务。设计原则参考：Github API v3
本次API文档采用swagger根据进行开发。swagger是一个开源的API工具，功能强大，这次作业只是略略一窥其貌，主要使用了swagger-editor来编写API文档

swagger-editor：https://github.com/swagger-api/swagger-editor
在线编辑器：http://editor.swagger.io/

该在线编辑器使用yaml语法来编辑文档，易于上手，并且还有很漂亮的UI进行实时响应。在写完文档后，还可以导出yaml文件进行备份或者使用Generate Client功能并选取html2生成一个文件夹，里面的index.html是本次文档的网页页面，可以直接在浏览器中打开查看。

• 在线编辑器展示:

• index.html页面展示：
  

部分API的编写

在生成API文档之后，我们使用goxygen脚手架来实现我们的前后端分离的简单Webapp，在经过对框架的一些小修改之后，服务端的基本目录如下：

在该目录下通过终端输入go run server.go即可开启后端服务，也可以使用go build进行构建。在本次团队项目的API编写中我主要负责的User部分的API编写，包括获取所有用户的具体信息和获取单个用户的具体信息等API。由于该脚手架已经自动帮我们写好了连接数据库和开启服务端服务等代码，所以我们只需要在适当的位置添加上我们的API路由和处理函数即可。并且该框架连接的mongoDB数据库，而go的第三方库mongomongo包使用文档集成了足够的数据库操作函数，我们可以使用该库对连接的数据进行增删改查操作，非常方便。下面就贴上两个API的主要实现代码：

• 获取所有用户的具体信息：

//GetUsersInfo get usersinfo
func (m MongoDB) GetUsersInfo() ([]*model.User, error) {
	res, err := m.database.Collection("user").Find(context.TODO(), bson.M{})
	if err != nil {
		log.Println("Error while fetching all users:", err.Error())
		return nil, err
	}

	var users []*model.User
	err = res.All(context.TODO(), &users)
	if err != nil {
		log.Println("Error while decoding all users:", err.Error())
		return nil, err
	}
	return users, nil
}

• 获取单个用户的具体信息

//GetAUserInfo get a userinfo
func (m MongoDB) GetAUserInfo(username string) ([]*model.User, error) {
	res, err := m.database.Collection("user").Find(context.TODO(), bson.M{"username": username})
	if err != nil {
		log.Println("Error while fetching a user:", err.Error())
		return nil, err
	}

	var user []*model.User
	err = res.All(context.TODO(), &user)
	if err != nil {
		log.Println("Error while decoding a user:", err.Error())
		return nil, err
	}
	return user, nil
}

实验总结

• 本次项目实现过程遇到的问题更多的并不是代码实现上面的问题，而是API设计上面的问题，关于API REST v3风格的API设计标准还是一知半解，设计起来才知道有多难。
• 对于团队项目一定要先确定好整体的分工以及项目实现的流程，只有当所有知道这两点之后才能更加有效率的完成一个团队项目。在这次团队项目中由于沟通问题而暴露出了很多问题，比如编写API时成员对同一个文件进行覆盖导致其他成员的代码丢失、在Github上强制执行推送导致其他成员的提交记录被覆盖，从而导致其他成员的贡献值丢失等问题。
• 这次前端使用React脚手架进行构建，在此之前还没有使用这个脚手架，这次又没有参与到前端的开发，以后有机会一定学习一下。