persagy-web-doc/docs/guides/interface

web接口

::: details 目录 [[toc]] :::

接口文档

接口文档，相当于后端对产品需求提供数据以及功能的一个说明书，为什么这样说那，一个产品的说明书，内容详细介绍，突出功能明确指出应该怎样操作执行的指令是什么，会达到什么样的效果， 减少客户和客服沟通的频率，或者不需要询问客服看说明书就能明白功能以及达到的效果。接口文档意是如此，我们不可能每完成一个接口都开会或发到工作群中给大家讲解，也不可能一个产品的 数据结构定好，所有的接口开发完统一大家一起开会做现场解说，不能保证所有的能记得所有内容，都会使用。为了高效而又节省时间需要我们写一个简单易懂的文档出来，而对于接口，在明确数 据结构以及功能，还要测试接口是否可用，是否正确处理了数据，是否达到了前端的效果。即使后端测试过了，前端也要测试功能，还需要每个属性结构进行确认，这就需要我们整理出一份详细的 文档出来，把功能、数据结构、示例都介绍详细、清楚，最好直接提供可以测试的接口文档，这样只要有一份接口文档就够了，不用再看着接口文档一个一个粘贴到别的工具上调试，节省了前端调 试沟通数据结构了解属性功能接口使用方式的时间。

接口文档调试工具

• swagger 接口文档调试工具，保证了代码和文档的一致性，swagger 是直接集成在后端的项目中。使用注解的方式在代码中进行了更改 swagger 也会随之变化。
• swagger 提供了接口测试功能，不需要安装 postmain , 文档中把每个属性、数据结构 接口的请求方式标注的很清楚，也可以把注意事项标记清楚。
• 通过注解的方式自动生成文档，只需要补录一些需要注意事项，一些简单的示例介绍，节省了编写文档的时间

点击 try it out 填写相应的参数

点击 Execute 直接即可进行接口测试

标准接口

• 标准通用接口增删改查统计
• 统一的请求体结构，应答结构
• web端操作符的使用
• 请求体重属性名不区分大小写，应答题返回标准的驼峰命名
• 支持的值类型：int、float、double、boolean、char、date

接口定义

• 以对象为主的对象接口 ，唯物主义思想模式定义接口，面向对象编程理念，对象都一致，有相同接口,有利于前段使用接口的标准化，结构化，模块化，提高代码复用性，节约开发测试维护成本；
• 规范化开发
• 查询条件灵活的多样的
• 专为应用服务的后台，比如数据中心就是围绕着物理世界或中台的壳，面向应用友好，主要针对应用和APP的需求，解决物理世界或中台对应用适配的问题

Web接口注意事项

• 属性名不加引号且属性名不区分大小写；name与NAME代表相同的属性。
• 属性名指的是实体类的属性名，不是指数据库的字段名（框架在操作数据库时，会自动将属性名转换为字段名）。
• 数值型值、布尔型值，在写表达式时不需要写引号；
• 字符串型值、日期型值，在写表达式时要写上单引号；
• 表达式“包含”，“前缀”，“后缀”只用于字符串型属性；
• 在“列表内”表达式，列表内的每个值的类型必须一致，否则会抛出异常；