项目/代码规范与Apifox介绍使用

(2)方法注释(Constructor)：
方法内部单行注释，在被注释语句上方另起一行，使用 // 注释。方法内部多行注释使用 /* */
注释，注意与代码对齐。所有的抽象方法（包括接口中的方法）必须要用 Javadoc 注释、除了返回值、参数异常说明外，还必须指出该方法做什么事情，实现什么功能。方法注释(Constructor)还可以用来声明该类的参数、返回等信息:

/**

* @author: fendo

* @methodsName: addUser

* @description: 添加一个用户

* @param: xxxx

* @return: String

* @throws:

*/

（3）代码块注释：解释你某一部分代码的用途

/**

* 实例化一个用户

* xxxxxxx

*/

User user=new User();

（4）单句注释：注释你单独的代码

User user=new User(); //实例化一个用户

（三）命名规范：

命名要让别人能看懂，驼峰命名，区分大小写。

（1）类名使用 UpperCamelCase 风格：
例如：UserController，FileController，BookService
（2）方法名、参数名、成员变量、局部变量都统一使用 lowerCamelCase 风格。
例如：getUserName(),userLogin(),getMessage();
（3）常量命名应该全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长。

例如：MAX_STOCK_COUNT / CACHE_EXPIRED_TIME
（4）抽象类命名使用 Abstract 或 Base 开头；异常类命名使用 Exception 结尾，测试类命名以它要测试的类的名称开始，以 Test 结尾。
（5）包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用单数形
式，但是类名如果有复数含义，类名可以使用复数形式。
（6）Service / DAO 层方法命名规约：
1）获取单个对象的方法用 get 做前缀。
2）获取多个对象的方法用 list 做前缀，复数结尾，如：listObjects
3）获取统计值的方法用 count 做前缀。
4）插入的方法用 save / insert 做前缀。
5）删除的方法用 remove / delete 做前缀。
6）修改的方法用 update 做前缀。
（7）领域模型命名规约：
1）数据对象：xxxDO，xxx 即为数据表名。
2）数据传输对象：xxxDTO，xxx 为业务领域相关的名称。
3）展示对象：xxxVO，xxx 一般为网页名称。
（8）所有整型包装类对象之间值的比较，全部使用 equals 方法比较。
说明：对于 Integer var = ? 在 -128 至 127 之间的赋值，Integer 对象是在 IntegerCache.cache 产生，会复用已有对象，这个区间内的 Integer 值可以直接使用 == 进行判断，但是这个区间之外的所有数据，都会在堆上产生，并不会复
用已有对象，这是一个大坑，推荐使用 equals 方法进行判断。
（9）浮点数之间的等值判断，基本数据类型不能使用 == 进行比较，包装数据类型不能使用 equals 进行判断。 BigDecimal 的等值比较应使用 compareTo() 方法，而不是 equals() 方法。
正例：
(1)指定一个误差范围，两个浮点数的差值在此范围之内，则认为是相等的。
float a = 1.0F - 0.9F ;
float b = 0.9F - 0.8F ;
float diff = 1e-6F ;
if ( Math . abs ( a - b ) < diff ) {
System . out . println ( "true" );
}
(2)使用 BigDecimal 来定义值，再进行浮点数的运算操作。
BigDecimal a = new BigDecimal ( "1.0" );
BigDecimal b = new BigDecimal ( "0.9" );
BigDecimal c = new BigDecimal ( "0.8" );
BigDecimal x = a . subtract ( b );
BigDecimal y = b . subtract ( c );
if ( x . compareTo ( y ) == 0) {
System . out . println ( "true" );
}

|----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|
| 标识符类型 | 命名规则 | 例子 |
| 包(Packages) | 一个唯一包名的前缀总是全部小写的ASCII字母并且是一个顶级域名，通常是com，edu，gov，mil，net，org，或1981年ISO 3166标准所指定的标识国家的英文双字符代码。包名的后续部分根据不同机构各自内部的命名规范而不尽相同。这类命名规范可能以特定目录名的组成来区分部门(department)，项目(project)，机器(machine)，或注册名(login names)。 | com.sun.eng com.apple.quicktime.v2 edu.cmu.cs.bovik.cheese |
| 类(Classes) | 命名规则：类名是个一名词，采用大小写混合的方式，每个单词的首字母大写。尽量使你的类名简洁而富于描述。使用完整单词，避免缩写词(除非该缩写词被更广泛使用，像URL，HTML) | class Raster; class ImageSprite; |
| 接口(Interfaces) | 命名规则：大小写规则与类名相似 | interface RasterDelegate; interface Storing; |
| 方法(Methods) | 方法名是一个动词，采用大小写混合的方式，第一个单词的首字母小写，其后单词的首字母大写。驼峰命名 | run(); runFast(); getBackground(); |
| 变量(Variables) | 除了变量名外，所有实例，包括类，类常量，均采用大小写混合的方式，第一个单词的首字母小写，其后单词的首字母大写。变量名不应以下划线或美元符号开头，尽管这在语法上是允许的。变量名应简短且富于描述。变量名的选用应该易于记忆，即，能够指出其用途。 | List <User> userList; String userName; |
| 常量(Constants) | 类常量和ANSI常量的声明，应该全部大写，单词间用下划线隔开。(尽量避免ANSI常量，容易引起错误) | static final int MIN_WIDTH = 4; static final int MAX_WIDTH = 999; static final int GET_THE_CPU = 1; |

（四）前后端规范：

（1）请求方法：对具体操作的定义，常见的请求方法如下：

a）GET：从服务器取出资源。（可以看作select操作）
b）POST：在服务器新建一个资源。（可以看作insert操作）
c）PUT：在服务器更新资源。（可以看作update操作）
d）DELETE：从服务器删除资源。（可以看作delete操作）
（2）请求的返回信息：

code：http的status code
- 如果有自己定义的额外的错误，那么也可以考虑用自己定义的错误码
message：对应的文字描述信息
- 如果是出错，则显示具体的错误信息
- 否则操作成功，一般简化处理都是返回OK
data
- 对应数据的json字符串
  - 如果是数组，则对应最外层是**[]** 的list
  - 如果是对象，则对应最外层是**{}** 的dict

java 复制代码

{
 "code": 200,
 "message": "new user has created",
 "data": {
   "id": "user-4d51faba-97ff-4adf-b256-40d7c9c68103",
   "firstName": "crifan",
   "lastName": "Li",
   "password": "654321",
   "phone": "13511112222",
   "createdAt": "2016-10-24T20:39:46",
   "updatedAt": "2016-10-24T20:39:46"
   ......
 }
}

（3）响应的状态码

出错问题：

1xx（信息性状态码）：表示接收的请求正在处理。
2xx（成功状态码）：表示请求正常处理完毕。 200就是请求返回成功。
3xx（重定向状态码）：需要后续操作才能完成这一请求。
4xx（客户端错误状态码）：表示请求包含语法错误或无法完成。 400 404 401 403 都是前端发送请求时候出的错误，前端先要查看问题，也有可能是后端写的出了错误。
5xx（服务器错误状态码）：服务器在处理请求的过程中发生了错误。后端问题，有可能抛出异常，服务器错误等等。

2XX 成功

200 ok（请求成功）

204 no content （请求成功，但是没有结果返回）

206 partial content （客户端请求一部分资源，服务端成功响应，返回一范围资源）

3XX 重定向

301 move permanently （永久性重定向）

302 found （临时性重定向）

303 see other （示由于请求对应的资源存在着另一个 URI，应使用 GET

方法定向获取请求的资源）

304 not modified （表示在客户端采用带条件的访问某资源时，服务端找到了资源，但是这个请求的条件不符合。跟重定向无关）

307 temporary redirect （跟302一个意思）

4XX 客户端错误

400 bad request （请求报文存在语法错误）

401 unauthorized （需要认证（第一次返回）或者认证失败（第二次返回））

403 forbidden （请求被服务器拒绝了）

404 not found （服务器上无法找到请求的资源）

5XX 服务器错误

500 internal server error （服务端执行请求时发生了错误）

503 service unavailable （服务器正在超负载或者停机维护，无法处理请求）

（五）其他规范：

（1）HTTP 请求通过 body 传递内容时，必须控制长度，超出最大长度后，后端解析会出错。
说明： nginx 默认限制是 1MB，tomcat 默认限制为 2MB，当确实有业务需要传较大内容时，可以调大服务器端的限制。
（2）不要在 finally 块中使用 return
说明： try 块中的 return 语句执行成功后，并不马上返回，而是继续执行 finally 块中的语句，如果此处存在 return 语句，则会在此直接返回，无情丢弃掉 try 块中的返回点。
（3）事务场景中，抛出异常被 catch 后，如果需要回滚，一定要注意手动回滚事务。
（4）可以使用日志进行记录信息，使用日志框架（SLF4J、 JCL---Jakarta Commons Logging）中的 API.

三、Apifox使用：

（一）下载与安装：

链接：点击链接，直接下载apifox（下载最新版就行）。Apifox - API 文档、调试、Mock、测试一体化协作平台。拥有接口文档管理、接口调试、Mock、自动化测试等功能，接口开发、测试、联调效率，提升 10 倍。最好用的接口文档管理工具，接口自动化测试工具。https://apifox.com/

（二）新建项目与邀请你的队友：

1.新建你的团队与新建项目：

邀请你的队友

2.新建接口与新建数据模型：

（1）确定好是什么请求（POST，GET，PUT，DELETE）：

（2）测试环境一定统一好，不同的环境url不一样：

（3）请求参数配置好：

有什么参数配置什么参数，给出参数示例，中文名，参数说明要有。

（4）响应要配置好：

比如不同的状态下返回什么样子的信息要规定好，成功示例，异常示例要有（方便前端）。

java 复制代码

{
    "code": 200,
    "message": "登入成功",
    "data": {
        "user_id": 27,
        "user_name": "孟霞",
        "user_password": "123456",
        "user_age": "15",
        "user_photo": "http://dummyimage.com/400x400",
        "user_last_time": "1996-12-11 09:03:49",
        "user_indentity": "messager",
        "user_birthday": "2024-02-23"
    }
}

（5）可以创建数据模型：

可以创建几个数据模型，在返回响应字段的适合很方便，也方便前端查看你的数据域东西。

（三）接口文档的书写规范

apifox的书写规范、与具体细节。

Apifox 快速入门 | Apifox 帮助文档https://apifox.com/help/

（1）在 API 接口文档的开头，应该有一部分介绍。这部分可以包括以下内容：

API 接口的名称和版本号
API 接口的功能和用途
API 接口的设计目的和原则
API 接口的适用范围和限制

这部分的目的是为了让读者了解该 API 接口的基本情况和背景信息。

（2）接口列表

接着，在 API 接口文档中，我们需要列出所有的接口。每个接口应该包含以下信息：

接口名称和描述
请求方法（GET、POST、PUT、DELETE 等）
请求路径（URL）
请求参数（包括 Query 参数和 Body 参数）
请求示例（可以包含请求头和请求体的完整示例）
响应状态码和描述
响应参数（包括 Header 参数和 Body 参数）
响应示例（可以包含响应头和响应体的完整示例）

这部分的目的是为了让读者能够快速了解每个接口的基本信息，并且能够根据文档中的示例来正确地使用接口。

（3）请求参数和响应参数说明

在接口列表之后，我们需要详细说明每个接口的请求参数和响应参数。这部分应该包括以下信息：

参数名称和描述
参数类型和格式
是否必填和默认值
参数示例

对于参数类型和格式，可以使用标准的数据类型和格式，也可以根据具体情况定义自己的数据类型和格式。对于是否必填和默认值，需要根据实际情况来确定。

（4）错误码说明

在使用 API 接口时，有时候会发生错误，此时需要返回一个错误码来说明错误的类型和原因。因此，在 API 接口文档中，我们需要详细说明所有可能的错误码。这部分应该包括以下信息：

错误码和描述
错误类型和原因
接口返回的错误码示例

这部分的目的是为了让读者了解所有可能的错误类型和原因，并且能够根据文档中的示例来正确地处理错误。

四、Debug功能（后端必须要会）

2分钟教会你如何Java中DeBug【IDEA中Java】_java工程中没有案例如何debug-CSDN博客https://blog.csdn.net/qq_43436117/article/details/113859737

五、测试类

（1）具体的操作：

定义一个测试类

建议：

测试类名：被测试的类名Test CalculatorTest

包名：xx.xx.xx.test cn.itcast.test

定义测试方法：可以独立运行

建议：

方法名：test测试的方法名 testAdd()

返回值：void

参数列表：空参

给方法加 @Test

导入Junit依赖环境

判定结果：

红色：失败

绿色：成功

我们一般使用Assert类下的静态方法assertEquals(expected, actual)去处理我们的期望结果和输出结果

Assert.assertEquals(3, result);

两个参数分别是：期望值程序结果值

为什么要使用Assert.assertEquals(expected, actual)去处理测试结果呢？

因为我们规定红色代表失败，绿色代表正确。当我们使用一个测试方法去测试一个计算机的加法方法时，最后只是输出这个结果（假如没有异常的发生）。如果我们输入1和3，我们期望得到结果4，但是我们输出的是2，我们期望得到的是4，这个时候得到的结果不符合我们的预期，但是运行结果仍然是绿色的（代表正确），是不是就不太正确，这个时候我们可以在最后使用Assert的assertEquals方法比较预期值和程序输出的结果值，如果相等，就会使绿色的，不相等就是红色的。这个时候是不是就符合我们对绿色和红色的定义了。

java 复制代码

package cn.itcast.test;

import cn.itcast.junit.Calculator;
import org.junit.Assert;
import org.junit.Test;

public class CalculatorTest {
    /**
     * 测试add方法
     */
    @Test
    public void testAdd(){
        Calculator  c = new Calculator();
        int a = 1, b = 2;
        int result = c.add(1, 2);
        Assert.assertEquals(3, result);
    }

    /**
     * 测试sub方法
     */
    @Test
    public void testSub(){
        Calculator  c = new Calculator();
        int a = 1, b = 2;
        int result = c.sub(1, 2);
        Assert.assertEquals(-1, 2);
    }
}

@Before

在一个测试方法之前加上@Before它就成为了初始化方法，在所有测试方法执行之前都会自动先执行该方法，一般用于资源的申请

@After

在一个测试方法之前加上@After它就成为了释放资源方法，在所有测试方法执行之后都会自动执行该方法。

被@Before修饰的方法会在测试方法执行之前先被执行

被@After修饰的方法会在测试方法执行之后被执行

被@Before或被@After修饰的方法无论测试方法是否出一场都会执行

（2）自动生成Test类插件

六、注意事项：

（1）接口文档后端书写，要写的清晰明确，能让你的前端看明白，规范书写，不要写了就自己能看明白，改写的名称默认值接口响应要写好。

（2）除了教的东西，可以自行学一些其他的东西，比如邮箱验证注册，验证码登入，c3p0，MD5加密，log日志，Result风格等等等。

（3）代码书写也要规范，逻辑要严谨；（cookie，session）该设置的设置；需要判空的地方要判空，可以增加安全性的地方可以学学，

（4）前后端要配合好，不要后端只做自己的，一句话也不跟前端说。前后端的交互响应，同样也是考核的一部分，占很大一部分，你们写的接口，仅仅在apifox跑通是不可以的，呈现在具体的前端页面上有没有出错，有没有逻辑问题等等这都可能需要考虑。

（一个人是打不了江山的！！！）

（5）在需求分析的时候，就规定好你们自己要做的功能和接口，如果你做了什么功能，前端没有做，你可以push她，如果她做了的东西需要你后端的接口/数据，你没有写，那就好好反思反思，多沟通多交流。

可以对标一下真正可以运行的项目或者相似的东西，比如购物网站。那你就对标淘宝，这个网站可能有的后端接口，可能有的功能模块，具体的细节。

（6）不要一味的追求多，要逻辑合理，能够简化的部分要学会简化。但是基本的接口数量和代码量也是要保证的。（我们当初写的接口基本都是40多）