项目规范文档（认证体系 & Result / ErrorCode 规范）

项目规范文档（认证体系 & Result / ErrorCode 规范）

 

一、文档目的

统一项目中登录、认证、Token、接口返回的行为语义，避免登录失败却返回 success、前端误判等问题。

 

---

 

二、统一返回结构（Result）

 

2.1 标准返回格式

```json

{

  "code": 0,

  "msg": "success",

  "data": {}

}

```

 

2.2 成功与失败判定

- code == 0 ：成功

- code != 0 ：失败

 

---

 

三、Result 使用规范

 

3.1 合法用法

```java

return Result.ok(data);

return Result.ok();

```

 

3.2 禁止用法

```java

return Result.ok("密码错误");

return new Result().ok("失败");

```

 

---

 

四、ErrorCode 规范

 

4.1 分区规则

- 0：成功

- 10000+：参数错误

- 20000+：登录/账号

- 21000+：Token/认证

- 50000+：系统错误

 

4.2 示例

```java

int ACCOUNT_PASSWORD_ERROR = 20002;

int TOKEN_EXPIRED = 21003;

```

 

---

 

五、Controller 层规范

- 失败一律 throw 异常

- 成功只有一个 return Result.ok

 

---

 

六、refreshToken / logout

- refreshToken 失败必须 code != 0

- logout 永远 Result.ok()

 

---

 

七、全局异常处理

```java

@ExceptionHandler(SxbException.class)

public Result<?> handle(SxbException e) {

    return Result.fail(e.getCode(), e.getMessage());

}

```

 

---

 

八、前端统一处理

```js

if (res.code !== 0) {

  clearToken();

  gotoLogin();

}

```

 

---

 

九、上线前体检清单

- login 失败不返回 Result.ok

- 异常不返回 success

- 前端只认 code