diff --git a/docs/chapter07.md b/docs/chapter07.md index 812b172..34e159d 100644 --- a/docs/chapter07.md +++ b/docs/chapter07.md @@ -244,10 +244,41 @@ public class CorsConfig { ### 7.3 登录功能开发 -实现简单的Jwt认证 +#### 7.3.1 登录接口API +[用户登录接口](./resources/用户登录接口.md) -spring boot 中自定义配置项 +#### 7.3.2 JWT介绍 + +JSON Web Token（JWT）是一种开放标准（RFC 7519），用于在网络应用环境间安全地传输信息。JWT可以用于身份验证，也可以用于信息交换。 + +每个JWT由三部分组成：Header（头部）、Payload（负载）和Signature（签名），它们之间用点（.）分隔。 + +- Header（头部）：通常包含两部分：令牌的类型（即JWT）和所使用的签名算法，如HMAC SHA256或RSA。 +- Payload（负载）：包含所要传递的信息。负载可以包含多个声明（claim），它们是关于实体（通常是用户）和其他数据的声明。 +- Signature（签名）：用于验证消息在传输过程中未被篡改，并且，对于使用私钥签名的令牌，还可以验证发送者的身份。签名是使用头部指定的算法和密钥生成的。 + +JWT的优势在于其无状态和可扩展性，它不需要在服务端存储会话信息，这使得它非常适合分布式系统和跨域应用。同时，JWT也可以被用于信息交换，因为它可以包含任何需要的信息，并且是自包含的，不需要查询数据库来获取用户状态。 + +在登录功能中，JWT通常用于在用户成功登录后生成一个令牌，这个令牌随后被用于验证用户的身份，以便用户可以访问受保护的资源。客户端将JWT存储在本地（通常是在Cookie或LocalStorage中），并在每次请求时将其作为请求头的一部分发送给服务器。服务器通过验证JWT的签名来确认用户的身份，并允许或拒绝访问请求的资源。 + +[体验JWT](https://jwt.io/) + +![jwt](./resources/imgs/jwt-example.png) + +参考： [JSON Web Token 入门教程](https://www.ruanyifeng.com/blog/2018/07/json_web_token-tutorial.html) + +#### 7.3.3 代码实现 + +示例项目中的jwt包下，实现了jwt的生成和验证方法。 + +AuthController类中添加登录方法，实现用户登录接口。 + +AuthService类中添加登录方法，实现用户登录功能。 + +#### 7.3.4 实现获取用户个人信息功能 + +[获取用户个人信息接口.md](./resources/获取用户个人信息接口.md) ### 7.4 发布文章功能开发 diff --git a/docs/resources/imgs/jwt-example.png b/docs/resources/imgs/jwt-example.png new file mode 100644 index 0000000..1db062d Binary files /dev/null and b/docs/resources/imgs/jwt-example.png differ diff --git a/docs/resources/用户登录接口.md b/docs/resources/用户登录接口.md new file mode 100644 index 0000000..19d6893 --- /dev/null +++ b/docs/resources/用户登录接口.md @@ -0,0 +1,81 @@ +## 1. 用户登录接口 + +### 1.1 接口描述 +用户输入账号、密码完成登录。 +### 1.2 请求URL +`/v1/auth/login` + +### 1.3 请求方式 +**POST** + +### 1.4 请求头 +| 头字段 | 必填 | 数据类型 | 描述 | +| ------------ | ---- | ------------- | -------------------------------- | +| Content-Type | 是 | application/json | 指定请求体的媒体类型为JSON | + +### 1.5 请求体参数 +| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 | 示例 | 允许空值 | +|-----------| ---- | -------- |--------| ---------------------------- | ------------ | -------- | +| username | 是 | 字符串 | 1-32字符 | 用于登录的账号（手机号或邮箱） | "user123" | 否 | +| password | 是 | 字符串 | 1-32字符 | 密码 | "p@ssw0rd" | 否 | + + +### 1.6 请求示例 +```http +POST /v1/auth/login +Host: {apiAddress} +Content-Type: application/json + +{ + "username": "a123", + "password": "123456" +} +``` + +### 1.7 返回参数说明 +| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 | +|------| ---- | -------- | -- |-----------| +| code | 是 | 整型 | | 错误码，0表示成功 | +| msg | 否 | 字符串 | | 错误信息描述 | +| data | 否 | json | | 具体业务数据 | + + +data结构说明： + +| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 | +|-------| ---- | -------- |------|-----------| +| token | 是 | 字符串 | 字符串 | jwt token | + +### 1.8 响应示例（成功） + +```json + {"code":0,"msg":"success","data":{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhMTIzIiwiaWF0IjoxNjg3NjQyNzU4LCJleHAiOjE2ODc2Njg3NTgsIm5iZiI6MTY4Nz"}} +``` +### 1.9 响应示例（错误） +```json +{ "code": 401, "msg": "验证失败" } +``` + +### 1.10 错误响应码参考 +更多响应错误码及含义，请参阅[API响应码表](URL/for/api/responseCode/table)。 + +### 1.11 安全性与认证 + + +### 1.12 测试环境 +访问测试环境以进行接口调试： +[https://test.apiAddress.com](https://test.apiAddress.com) + +### 1.13 版本管理 +本API通过URI路径进行版本控制。请在请求URL中包含`/v1`以使用当前版本。 + +### 1.14 更新记录 +- **2024-04-29**：发布文档初始版本。 + + +### 1.15 联系支持 +如需帮助或对API有任何疑问，请通过电子邮件与我们联系：[support@api.com](mailto:support@api.com)。 + +### 1.16 反馈与建议 +发现文档问题或有改进建议？请填写[反馈表单](https://forms.api.com/feedback)与我们分享。 + diff --git a/docs/resources/获取用户个人信息接口.md b/docs/resources/获取用户个人信息接口.md new file mode 100644 index 0000000..f3a1e5d --- /dev/null +++ b/docs/resources/获取用户个人信息接口.md @@ -0,0 +1,94 @@ +## 1. 获取用户个人信息接口 + +### 1.1 接口描述 +获取当前登录用户的个人信息。 +### 1.2 请求URL +`/v1/user/info` + +### 1.3 请求方式 +**GET** + +### 1.4 请求头 +| 头字段 | 必填 | 数据类型 | 描述 | +| ------------ | ---- | ------------- | -------------------------------- | + + +### 1.5 请求体参数 +| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 | 示例 | 允许空值 | +|-----------| ---- | -------- | -------- | ---------------------------- | ------------ | -------- | + + +### 1.6 请求示例 +```http +GET /v1/user/info +``` + +### 1.7 返回参数说明 +| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 | +|------| ---- | -------- | -- |-----------| +| code | 是 | 整型 | | 错误码，0表示成功 | +| msg | 否 | 字符串 | | 错误信息描述 | +| data | 否 | json | | 具体业务数据 | + +data结构说明： + +| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 | +|----------| --- | -------- |--|------| +| id | 是 | 整型 | | 用户id | +| username | 是 | 字符串 | 1-32字符 | 登录账号 | +| ... | | | | | +| follows | 是 | 整型 | | 关注我的 | +| followings | 是 | 整型 | | 我关注的 | +| tweets_count | 是 | 整型 | | | + + +### 1.8 响应示例（成功） + +```json +{ + "code": 0, + "msg": "success", + "data": { + "id": 100066, + "nickname": "xyz", + "username": "xyz", + "status": 1, + "avatar": "https://assets.paopao.info/public/avatar/default/jackson.png", + "phone": "", + "is_admin": false, + "created_on": 1714290963, + "follows": 0, + "followings": 0, + "tweets_count": 4 + } +} +``` +### 1.9 响应示例（错误） +```json +{ "code": 500, "msg": "内部错误" } +``` + +### 1.10 错误响应码参考 +更多响应错误码及含义，请参阅[API响应码表](URL/for/api/responseCode/table)。 + +### 1.11 安全性与认证 + + +### 1.12 测试环境 +访问测试环境以进行接口调试： +[https://test.apiAddress.com](https://test.apiAddress.com) + +### 1.13 版本管理 +本API通过URI路径进行版本控制。请在请求URL中包含`/v1`以使用当前版本。 + +### 1.14 更新记录 +- **2024-05-07**：添加data结构说明 +- **2024-04-29**：发布文档初始版本。 + + +### 1.15 联系支持 +如需帮助或对API有任何疑问，请通过电子邮件与我们联系：[support@api.com](mailto:support@api.com)。 + +### 1.16 反馈与建议 +发现文档问题或有改进建议？请填写[反馈表单](https://forms.api.com/feedback)与我们分享。 +