开发规范

命名规范
API接口规范

统一的API风格和规范对于提高开发效率、易用性和可维护性非常重要，可以使开发者更容易地理解和使用API，从而提高整个项目的质量和成功率。

可读性：遵循统一的规范和风格使API更容易阅读和理解。开发者在阅读API文档或查看端点时，可以更快地理解它们的作用和用法
一致性：统一的API风格和规范有助于提高整个应用程序的一致性。这使得开发者在使用不同的API时能够更快地适应和理解它们的行为
易用性：统一的API风格和规范提高了API的易用性，因为开发者只需了解一种规范即可与整个API进行交互
提高开发效率：当API遵循统一的风格和规范时，开发者可以减少在不同端点(系统/模块)之间进行上下文切换的时间。这可以提高开发者的工作效率，并减少错误和遗漏的可能性
可维护性：遵循统一的API风格和规范使得代码更容易维护。当需要对API进行更改或扩展时，遵循统一的规范可以确保这些更改不会导致混乱或不一致的行为
更好的协作：在团队开发中，统一的API风格和规范有助于确保每个团队成员都遵循相同的约定，从而提高协作效率
易于扩展：统一的API风格和规范可以使得API更易于扩展，因为开发者在添加新功能时可以遵循现有的约定，确保与现有API的兼容性

命名规范

分类	规范项	规范	描述	示例
数据库	数据库名	单数+中划线/下划线	如果包含多个单词，除了最后一个，其他建议使用缩写	hw-telemetry
	表名 & ORM类名单复数	表名复数模型类单数	复数观点：表存储的是一个实体的多个实例对象例如) 将所有客户信息存储在一个表中，customer表示一个实体，customers表中的所有行都代表实体customer的实例，由于该表存储了客户的多个实例，因此要将表名设为复数单数观点：当指向数据库记录时，使用复数名称来描述单个项目会让人感到困惑例如) 当您只指向一个客户时，为什么要使用customers.name? 另外在SQL语句中，SELECT customer.name感觉比SELECT customers.name更适合方案：数据库表名用复数，ORM模型类用单数	`class User(ModelBase, ModelMixin, UserMixin): # 单数 __tablename__ = 'sys_users' # 复数 id = Column(Integer, primary_key=True) username = Column(String(50), unique=True, nullable=False) password = Column(String(100), nullable=False) email = Column(String(120), unique=True, nullable=False) created_at = Column(DateTime(), default=datetime.now) # 列名下划线连接 updated_at = Column(DateTime(), default=datetime.now, onupdate=datetime.now)`
	表名连接词	下划线	中划线可能导致SQL异常，需额外处理例如) 执行 SELECT * FROM temp_01-01-000001，会产生异常(SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near '-01-000001' at line 1)，需要写成 SELECT * FROM `temp_01-01-000001`
	列名连接词	下划线
页面导航	资源/模块单复数	复数	如果路由表示的是一个资源集合（例如，用户、文章、产品等），使用复数形式更为合适。如果路由表示的是一个特定的操作（例如，登录、注册、搜索等），则使用单数形式。请参考github/gitlab/gmail/pypi/estore等网站	资源集合：/users, /articles, /products 特定操作：/login, /signup, /search
	连接词	中划线	可读性：中划线使得URL更易于阅读和理解，因为它们在视觉上清晰地将单词分隔开。 SEO（搜索引擎优化）：搜索引擎如谷歌更倾向于对含有中划线的URL进行排名。谷歌已经公开表示，它们的算法会将中划线视为词汇间的分隔符，而将下划线视为连接符。这意味着使用中划线的URL在搜索引擎排名中可能获得更好的位置。	使用中划线：https://example.com/user-profile 使用下划线：https://example.com/user_profile（不推荐）
	AJAX请求URL(flask)	带斜杠	避免重定向(只针对flask应用，其他语言和框架根据情况设置)	[GET] http://127.0.0.1:666/api/v1.0/sys-users/
API	资源/模块单复数	复数	如果路由表示的是一个资源集合（例如，用户、文章、产品等），使用复数形式更为合适。如果路由表示的是一个特定的操作（例如，登录、注册、搜索等），则使用单数形式。和页面导航&权限控制统一。	@app.route('/users', methods=['GET'])
	连接词	中划线	中划线使得URL更易于阅读和理解，因为它们在视觉上清晰地将单词分隔开，请参考Google URL规范	@app.route('/devices/sync-from', methods=['POST'])
	URL参数 & 数据key	小写+下划线
	URL是否以斜杠结束 (flask)	是	带斜杠的API既可以处理带斜杠的请求(/users/)，又可以通过重定向处理不带斜杠的请求(/users) 不带斜杠的API只能处理不带斜杠的请求(/users) 以上逻辑只针对flask应用，其他语言和框架待定
协作开发	Postman使用	Postman使用	使用项目Variables，而不是Environment 注释(必填/格式/...) 自动设置登录token

以上命名请全部使用小写，另外也不推荐驼峰(/sysUser)或直接拼接(/sysuser)的命名方式。

API接口规范

在RESTful规范的基础上，对API接口URL和交互数据格式进行了定制化和规范化。

列表查询

查询某个数据模型的全部数据列表

Method	GET
URL	http://{{server_url}}/api/v1.0/{resources}/
Payload	-
Return	包含状态和数据列表/异常信息的json对象
	-成功	`{ "data": [ //数据列表 { "email": "admin@focus-ui.com", "id": 1, "name": "administrator", "role_id": 1, "status": "enable", "type": "local", "username": "admin" }, { "email": "test@focus-ui.com", "id": 2, "name": "abc", "phone": "", "role_id": 2, "status": "enable", "type": "local", "username": "test" } ], "status": "success" //状态，请求成功 }`
	-失败	`{ "status": "fail", //状态，请求成功，但是处理异常 "message": "Unauthorized", //异常信息，未授权 "status_code": "uri_unauthorized" //状态码 }`
备注	请求失败有两种情况请求失败，例如服务器异常/客户端错误等，这类异常是服务器没有catch住的，需要通过HTTP 响应代码进行判断处理请求成功，但处理失败，例如未授权，这类异常是服务器catch住的，可以通过请求结果返回的status/status_code进行判断处理，这里的status_code可用于客户端国际化

单个查询

查询某个数据模型的指定数据

Method	GET
URL	http://{{server_url}}/api/v1.0/{resources}/[pk]/
Payload	-
Return	包含状态和数据列表/异常信息的json对象
	-成功	`{ "data": { "email": "admin@focus-ui.com", "id": 1, "name": "administrator", "role_id": 1, "status": "enable", "type": "local", "username": "admin" }, "status": "success" //状态，请求成功 }}`
	-失败	`{ "status": "fail", //状态，请求成功，但是处理异常 "message": "Data Not Found", //异常信息，数据不存在 "status_code": "db_data_not_found" //状态码 }`
备注

条件查询

包含分页、搜索、排序等的条件查询

Method	POST
URL	http://{{server_url}}/api/v1.0/{resources}/pss/ http://{{server_url}}/api/v1.0/{resources}/query_pss/
Payload	分页/搜索/排序等查询条件
	`{ "search": { //搜索/过滤条件，多个条件之间是 AND的关系 "like": "abc", //-模糊查询，匹配所有可供模糊查询的列中的字符串 "name": "cde" //-精确查询，完全匹配 }, "sort": { //排序条件 "field": "name", //-排序的属性 "order": "asc" //-排序的顺序，顺序asc或倒序desc }, "page": { //分页属性 "offset": 0, //-当前页数据的偏移数 "size": 20 //-当前页的数据数量 } }`
Return	包含状态和数据列表/异常信息的json对象
	-成功	{ "data": { //数据对象，添加了count属性 "count": 26, //符合条件的数据总数，可用于分页 "data": [ //数据列表 { "action": "add", "created_at": "Tue, 30 Mar 2021 15:57:56 GMT", "id": 3, "module": "template", "result": "success", "user_ip": "127.0.0.1", "user_name": "administrator", "username": "admin" }, { "action": "update", "created_at": "Tue, 30 Mar 2021 15:58:23 GMT", "id": 4, "module": "template", "result": "success", "user_ip": "127.0.0.1", "user_name": "administrator", "username": "admin" }, ……. ] }, "status": "success" //状态，请求成功 }
	-失败	`{ "status": "fail", //状态，请求成功，但是处理异常 "message": "Unauthorized", //异常信息，未授权 "status_code": "uri_unauthorized" //状态码 }`
备注	采用POST的方式，以更好的组织请求条件数据

添加

添加数据

Method	POST
URL	http://{{server_url}}/api/v1.0/{resources}/
Payload	要添加的json数据对象
	`{ "username": "taozh", "password": "123456", "name": "Zhang Tao", "email": "taozh@focus-ui.com", "role_id": 1 }`
Return	包含状态和添加成功以后的模型数据/异常信息的json对象
	-成功	`{ "data": { "created_at": "Mon, 12 Mar 2022 09:23:14 GMT", "email": "taozh@focus-ui.com", "id": 3, //生成的数据库ID，可用于删除/编辑等操作 "name": "Zhang Tao", "role_id": 1, "status": "enable", "type": "local", "updated_at": "Mon, 12 Mar 2022 09:23:14 GMT", "username": "taozh" }, "status": "success" //状态，请求成功 }`
	-失败	`{ "status": "fail", //状态，请求成功，但是处理异常 "message": "Data Already Exists", //异常信息，数据已存在 "status_code": "db_data_already_exist" //状态码 }`
备注

删除

删除指定的数据

Method	DELETE
URL	http://{{server_url}}/api/v1.0/{resources}/[pk]/
Payload	-
Return	包含状态和删除成功以后的模型数据/异常信息的json对象
	-成功	`{ "data": { //被删除的数据信息 "created_at": "Mon, 14 Mar 2022 09:23:14 GMT", "email": "taozh@focus-ui.com", "id": 3, //可用于前端删除数据 "name": "Zhang Tao", "role_id": 1, "status": "enable", "type": "local", "updated_at": "Mon, 14 Mar 2022 09:23:14 GMT", "username": "taozh" }, "status": "success" //状态，请求成功 }`
	-失败	`{ "status": "fail", //状态，请求成功，但是处理异常 "message": "Data Not Found", //异常信息，数据不存在 "status_code": "db_data_not_found" //状态码 }`
备注	在URL中指定要删除的主键信息

修改

修改指定的数据，分为局部修改和全量替换

局部修改

只对传递的数据中指定的属性进行更新，数据中没有的属性保持不变

Method	PATCH
URL	http://{{server_url}}/api/v1.0/{resources}/ http://{{server_url}}/api/v1.0/{resources}/[pk]/
Payload	包含主键信息的要修改数据的json对象
	`{ "id":3, //要修改数据的主键 "password": "abcdef" //要修改的属性，除password以外的属性保持不变 }`
Return	包含状态和修改成功以后的模型数据/异常信息的json对象
	-成功	`{ "data": { //修改以后的数据信息 "created_at": "Mon, 14 Mar 2022 09:40:22 GMT", "email": "taozh@focus-ui.com", "id": 3, //可用于前端数据处理 "name": "Zhang Tao", "role_id": 1, "status": "enable", "type": "local", "updated_at": "Mon, 14 Mar 2022 09:49:38 GMT", "username": "taozh" }, "status": "success" //状态，请求成功 }`
	-失败	`{ "status": "fail", //状态，请求成功，但是处理异常 "message": "Data Not Found", //异常信息，数据不存在 "status_code": "db_data_not_found" //状态码 }`
备注	主键既可以放在URL中，也可以放在Payload中，URL中的主键优先级高于Payload中的主键(主键放在Payload中，可能会简化client端的API调用)

全量替换

以替换的方式对数据进行替换，如果属性不存在则置空

Method	PUT
URL	http://{{server_url}}/api/v1.0/{resources}/ http://{{server_url}}/api/v1.0/{resources}/[pk]/
Payload	包含主键信息的要修改的全量数据json对象
	`{ "id": 3, //要修改数据的主键 "username": "taozh", //要修改数据的属性，如果属性不存在，则将数据库中对应的属性置空 "password": "abcdef", "name": "Tao Zhang", "email": "taozh@focus-ui.com", "role_id": 2 }`
Return	包含状态和修改成功以后的模型数据/异常信息的json对象
	-成功	`{ "data": { //修改以后的数据信息 "created_at": "Mon, 14 Mar 2022 09:40:22 GMT", "email": "taozh@focus-ui.com", "id": 3, "name": "Tao Zhang", "role_id": 1, "status": "enable", "type": "local", "updated_at": "Mon, 14 Mar 2022 09:49:38 GMT", "username": "taozh" }, "status": "success" //状态，请求成功 }`
	-失败	`{ "status": "fail", //状态，请求成功，但是处理异常 "message": "Data Not Found", //异常信息，数据不存在 "status_code": "db_data_not_found" //状态码 }`
备注	除非场景特殊，一般通过PATCH的方式进行更新即可

多数据查询

一次查询多个模型的所有数据

Method	GET
URL	http://{{server_url}}/api/v1.0/{resources}/multi/ http://{{server_url}}/api/v1.0/{resources}/query_multiple/
Payload	-
Return	包含状态和数据列表/异常信息的json对象
	-成功	{ "data": { //包含多个模型数据列表的数据对象 "roles": [ //模型数据列表A { "created_at": "Thu, 14 Jan 2021 12:19:27 GMT", "default": false, "description": "", "id": 1, "name": "Manager", "updated_at": "Fri, 15 Jan 2021 15:14:50 GMT" }, { "created_at": "Thu, 08 Apr 2021 10:02:25 GMT", "default": false, "description": "abc", "id": 2, "name": "Guest", "updated_at": "Tue, 26 Oct 2021 16:06:53 GMT" } ], "users": [ //某个模型数据列表B { "created_at": "Thu, 14 Jan 2021 12:19:27 GMT", "email": "admin@focus-ui.com", "id": 1, "name": "administrator", "role_id": 1, "status": "enable", "type": "local", "updated_at": "Thu, 10 Jun 2021 17:49:33 GMT", "username": "admin" }, { "created_at": "Thu, 08 Apr 2021 09:55:04 GMT", "description": "", "email": "test@focus-ui.com", "id": 2, "name": "abc", "phone": "", "role_id": 2, "status": "enable", "type": "local", "updated_at": "Thu, 18 Nov 2021 19:58:55 GMT", "username": "test" } ] }, "status": "success" //状态，请求成功 }
	-失败	`{ "status": "fail", //状态，请求成功，但是处理异常 "message": "Unauthorized", //异常信息，未授权 "status_code": "uri_unauthorized" //状态码 }`
备注	主要为了减少请求次数，方便前端使用

批量添加

批量添加数据

Method	POST
URL	http://{{server_url}}/api/v1.0/{resources}/bulk/
Payload	要批量添加的json数据对象列表
	`[ { "username": "taozh", "password": "123456", "name": "Zhang Tao", "email": "taozh@focus-ui.com", "role_id": 1 }, { "username": "yhzh", "password": "123456", "name": "Zhang Yiheng", "email": "yhzh@focus-ui.com", "role_id": 1 } ]`
Return	包含状态和添加的模型数据列表(Payload中的)/异常信息的json对象
	-成功	`{ "data": [ { "username": "taozh", "password": "123456", "name": "Zhang Tao", "email": "taozh@focus-ui.com", "role_id": 1 }, { "username": "yhzh", "password": "123456", "name": "Zhang Yiheng", "email": "yhzh@focus-ui.com", "role_id": 1 } ], "status": "success" //状态，请求成功 }`
	-失败	`{ "status": "fail", //状态，请求成功，但是处理异常 "message": "Data Already Exists", //异常信息，数据已存在 "status_code": "db_data_already_exist" //状态码 }`
备注	整个操作为一个原子操作(全部成功/全部失败)

批量删除

批量删除指定的数据

Method	DELETE
URL	http://{{server_url}}/api/v1.0/{resources}/bulk/[ids]/
Payload	要批量删除的数据对象列表，列表中的项可以是主键值也可以是查询条件组成的对象
	`[11, 12, 13, 14, 15] //主键值 [{'id': 11}, {'id': 12}, {'id': 13}] //查询条件`
Return	包含状态和删除成功的数量/异常信息的json对象
	-成功	`{ "data": 3, //删除的数据数量 "status": "success" //状态，请求成功 }`
	-失败	`{ "status": "fail", //状态，请求成功，但是处理异常 "message": "Data In Use", //异常信息，数据不存在 "status_code": "db_data_in_use" //状态码 }`
备注	删除数据的信息，可以通过请求Url或Payload发送，示例如下 http://{{flaskz_server_url}}/api/v1.0/ex-employees/bulk/16,17,18,19,20 http://{{flaskz_server_url}}/api/v1.0/ex-employees/bulk/ Payload = [11, 12, 13, 14, 15] 操作会删除在数据库中存在的数据，如果不存在会跳过，返回结果是成功删除的数量

批量修改(局部)

批量修改数据

Method	PATCH
URL	http://{{server_url}}/api/v1.0/{resources}/bulk/
Payload	要批量修改的json数据对象列表
	`[ { "id": 1, //主键值 "role_id": 2 //新的值 }, { "id": 2, "role_id": 2 }, ]`
Return	包含状态和修改的模型数据列表(Payload中的)/异常信息的json对象
	-成功	`{ "data": [ { "id": 1, "role_id": 2 }, { "id": 2, "role_id": 2 }, ], "status": "success" //状态，请求成功 }`
	-失败	`{ "status": "fail", //状态，请求成功，但是处理异常 "message": "Data Already Exists", //异常信息，数据已存在 "status_code": "db_data_already_exist" //状态码 }`
备注	整个操作为一个原子操作(全部成功/全部失败)，如果数据在数据库中不存在，则会跳过

以上API请求和结果中的数据字段key统一使用下划线连接