From e71bbf3eb5ea70fa81a476a98f8eb028d7f2cd63 Mon Sep 17 00:00:00 2001 From: many2many <6168830@qq.com> Date: Wed, 15 May 2024 04:46:48 +0800 Subject: [PATCH] [add]docs & --- docs/api doc/用户注册接口.md | 22 ++--- docs/api doc/用户登录接口.md | 22 ++--- docs/api doc/获取用户个人信息接口.md | 94 +++++++++++++++++++ docs/guides/git工作流.md | 32 +++++++ .../任务3-Sprint-1-创建spring boot初始项目.md | 41 ++++++++ .../任务8-Sprint-1-获取当前用户信息接口.md | 5 +- src/main/java/com/lk/paopao/dto/UserDto.java | 4 +- src/main/resources/application.yml | 6 +- 8 files changed, 198 insertions(+), 28 deletions(-) create mode 100644 docs/api doc/获取用户个人信息接口.md create mode 100644 docs/guides/git工作流.md diff --git a/docs/api doc/用户注册接口.md b/docs/api doc/用户注册接口.md index af1fb5f..00ca989 100644 --- a/docs/api doc/用户注册接口.md +++ b/docs/api doc/用户注册接口.md @@ -1,5 +1,3 @@ -# RESTFul API 文档 v1.0 - ## 1. 用户注册 ### 1.1 接口描述 @@ -35,18 +33,18 @@ Content-Type: application/json ``` ### 1.7 返回参数说明 -| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 | -|-----------| ---- | -------- | -------- | ---------------------------- | -| code | 是 | 整型 | | 错误码，200表示成功 | -| message | 否 | 字符串 | 1-50字符 | 错误信息描述 | -| data | 否 | json | | 具体业务数据 | +| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 | +|------| ---- | -------- | -- |-----------| +| code | 是 | 整型 | | 错误码，0表示成功 | +| msg | 否 | 字符串 | | 错误信息描述 | +| data | 否 | json | | 具体业务数据 | data结构说明： -| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 | -|-----------| ---- | -------- | -------- | ---------------------------- | -| id | 是 | 整型 | | 用户id | -| username | 是 | 字符串 | 1-50字符 | 登录账号| +| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 | +|-----------| ---- | -------- |--------| ---------------------------- | +| id | 是 | 整型 | | 用户id | +| username | 是 | 字符串 | 1-32字符 | 登录账号| @@ -57,7 +55,7 @@ data结构说明： ``` ### 1.9 响应示例（错误） ```json -{ "code": 10001, "msg": "验证码无效" } +{ "code": 409, "msg": "用户名存在" } ``` ### 1.10 错误响应码参考 diff --git a/docs/api doc/用户登录接口.md b/docs/api doc/用户登录接口.md index 6b040e3..19d6893 100644 --- a/docs/api doc/用户登录接口.md +++ b/docs/api doc/用户登录接口.md @@ -1,5 +1,3 @@ -# RESTFul API 文档 v1.0 - ## 1. 用户登录接口 ### 1.1 接口描述 @@ -16,10 +14,10 @@ | Content-Type | 是 | application/json | 指定请求体的媒体类型为JSON | ### 1.5 请求体参数 -| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 | 示例 | 允许空值 | -|-----------| ---- | -------- | -------- | ---------------------------- | ------------ | -------- | -| username | 是 | 字符串 | 1-50字符 | 用于登录的账号（手机号或邮箱） | "user123" | 否 | -| password | 是 | 字符串 | 1-50字符 | 密码 | "p@ssw0rd" | 否 | +| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 | 示例 | 允许空值 | +|-----------| ---- | -------- |--------| ---------------------------- | ------------ | -------- | +| username | 是 | 字符串 | 1-32字符 | 用于登录的账号（手机号或邮箱） | "user123" | 否 | +| password | 是 | 字符串 | 1-32字符 | 密码 | "p@ssw0rd" | 否 | ### 1.6 请求示例 @@ -35,11 +33,11 @@ Content-Type: application/json ``` ### 1.7 返回参数说明 -| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 | -|-----------| ---- | -------- | -------- | ---------------------------- | -| code | 是 | 整型 | | 错误码，200表示成功 | -| message | 否 | 字符串 | 1-50字符 | 错误信息描述 | -| data | 否 | json | | 具体业务数据 | +| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 | +|------| ---- | -------- | -- |-----------| +| code | 是 | 整型 | | 错误码，0表示成功 | +| msg | 否 | 字符串 | | 错误信息描述 | +| data | 否 | json | | 具体业务数据 | data结构说明： @@ -55,7 +53,7 @@ data结构说明： ``` ### 1.9 响应示例（错误） ```json -{ "code": 10001, "msg": "验证失败" } +{ "code": 401, "msg": "验证失败" } ``` ### 1.10 错误响应码参考 diff --git a/docs/api doc/获取用户个人信息接口.md b/docs/api doc/获取用户个人信息接口.md new file mode 100644 index 0000000..e7d5ad6 --- /dev/null +++ b/docs/api doc/获取用户个人信息接口.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 /api/user/signup +``` + +### 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)与我们分享。 + diff --git a/docs/guides/git工作流.md b/docs/guides/git工作流.md new file mode 100644 index 0000000..b502d80 --- /dev/null +++ b/docs/guides/git工作流.md @@ -0,0 +1,32 @@ +### 单一`master`分支的Git工作流: + +1. **仓库初始化**： + - 在GitHub、GitLab或其他代码托管平台上创建一个新的仓库。 + - 在本地机器上，使用`git clone`命令克隆远程仓库到本地。 + +2. **工作开始**： + - 进入项目目录，使用`cd`命令。 + - 确保始终处于`master`分支，可通过`git branch`查看当前分支，或使用`git checkout master`切换到`master`分支。 + +3. **日常开发**： + - 在`master`分支上直接进行文件的修改、新增或删除。 + - 使用`git status`查看工作区的状态，了解哪些文件已被修改或新增。 + - 使用`git add .`或`git add `将改动的文件添加到暂存区。 + - 使用`git commit -m "commit message"`提交改动到本地仓库，记得附上清晰的提交信息。 + +4. **推送到远程仓库**： + - 使用`git push origin master`将本地`master`分支的改动推送到远程仓库的`master`分支。 + - 如果是首次推送，可能需要添加`-u`参数来建立跟踪关系，如`git push -u origin master`。 + +5. **协作与冲突解决**： + - 在多人协作时，确保及时拉取远程的最新改动到本地，使用`git pull origin master`。 + - 如果出现冲突，Git会提示冲突文件，需要手动编辑这些文件解决冲突，保留或合并必要的改动。 + - 解决冲突后，再次使用`git add`和`git commit`提交解决冲突后的版本，并推送。 + +6. **代码审查与反馈**： + - 即使在简化的工作流中，也应该鼓励团队成员相互查看提交的代码，可以通过Pull Request（即使是在同一个分支内）或代码审查工具来进行。 + +7. **版本标记**： + - 对于重要的里程碑或发布版本，可以使用`git tag`命令打标签，例如`git tag v1.0.0`，然后使用`git push origin --tags`将标签推送到远程仓库。 + +尽管此流程简单，但重要的是要意识到，随着项目复杂度和团队规模的增长，这种单一`master`分支的模式很容易导致混乱和错误。推荐过渡到更成熟的工作流，比如引入`develop`分支作为日常开发分支，以及使用功能分支进行特性开发和隔离，最终通过 Pull Request 合并到主分支，以保持代码质量和团队协作效率。 \ No newline at end of file diff --git a/docs/tasks/任务3-Sprint-1-创建spring boot初始项目.md b/docs/tasks/任务3-Sprint-1-创建spring boot初始项目.md index 5f8531d..8eb726a 100644 --- a/docs/tasks/任务3-Sprint-1-创建spring boot初始项目.md +++ b/docs/tasks/任务3-Sprint-1-创建spring boot初始项目.md @@ -148,6 +148,47 @@ springdoc: ``` + +- **JSON配置项** + +在`application.yml`中添加配置,设置JSON的属性命名策略为SNAKE_CASE： + +```yaml +spring: + jackson: + property-naming-strategy: SNAKE_CASE # 驼峰转下划线 +``` + +在Spring Boot应用中，可以通过`spring.jackson`命名空间下的配置项来定制Jackson库的行为，以适应不同的JSON序列化和反序列化需求。以下是一些关键的配置项示例及其功能： + +> **默认属性包含策略**: + - `spring.jackson.default-property-inclusion`: 控制哪些属性会被序列化到JSON中，可选值包括`ALWAYS`, `NON_NULL`, `NON_EMPTY`, `USE_DEFAULTS`, `NON_ABSENT`, 和 `CUSTOM`。例如，设置为`NON_NULL`可避免null值的字段出现在JSON输出中。 +> **日期格式化**: + - `spring.jackson.date-format`: 允许配置日期格式字符串，或者指定一个日期格式化类的全限定名，如使用`java.text.SimpleDateFormat`的格式。 + - `spring.jackson.time-zone`: 设置日期时间序列化和反序列化时使用的时区。 + +> **缩进和美化输出**: + - `spring.jackson.serialization.indent-output`: 布尔值，决定是否在输出的JSON中加入缩进以美化格式，默认为`false`。 + +> **时间戳格式**: + - `spring.jackson.serialization.write-dates-as-timestamps`: 决定日期是否应该被序列化为时间戳（毫秒数）而不是字符串格式，默认为`true`。 + +> **未知属性处理**: + - `spring.jackson.deserialization.fail-on-unknown-properties`: 当JSON中包含Java对象模型中不存在的属性时，决定是否抛出异常，默认为`false`意味着忽略未知属性。 + +> **属性命名策略**: + - `spring.jackson.property-naming-strategy`: 可以设置属性命名策略，如`LOWER_CAMEL_CASE`, `UPPER_CAMEL_CASE`, `KEBAB_CASE`, `SNAKE_CASE`, 或自定义实现的全限定名。 + +> **特性包含与忽略**: + - 可以通过特定的配置来控制Jackson的特性，比如`spring.jackson.features.*`，这里`*`代表Jackson中的特性标识，例如`FAIL_ON_UNKNOWN_PROPERTIES`等。 + +> **自定义ObjectMapper**: + - 如果上述配置不能满足需求，可以通过定义一个`ObjectMapper` Bean来实现更复杂的自定义配置。 + +请注意，实际可用的配置项可能依据Spring Boot的版本不同而有所差异，建议查阅对应版本的官方文档以获取最新和最准确的配置信息。 + + + #### 6、配置h2数据库和JPA 项目使用h2数据库作为默认的数据库，并使用JPA作为ORM框架。 diff --git a/docs/tasks/任务8-Sprint-1-获取当前用户信息接口.md b/docs/tasks/任务8-Sprint-1-获取当前用户信息接口.md index 9e037ee..7a577de 100644 --- a/docs/tasks/任务8-Sprint-1-获取当前用户信息接口.md +++ b/docs/tasks/任务8-Sprint-1-获取当前用户信息接口.md @@ -27,10 +27,11 @@ public class UserDto implements Serializable { String phone; Byte status; String avatar; - Long balance; Boolean isAdmin; + Integer follows=0; + Integer followings=0; + Integer tweetsCount=0; } - ``` > @Value 是 Lombok 库提供的一个注解，用于简化 Java 类的编写。当这个注解应用在一个类上时，Lombok 会自动为类的所有字段生成以下内容： - 私有字段（Private fields）：所有字段默认变为私有，并且没有公共访问器（getter 和 setter）。 diff --git a/src/main/java/com/lk/paopao/dto/UserDto.java b/src/main/java/com/lk/paopao/dto/UserDto.java index 9592fda..4df5eca 100644 --- a/src/main/java/com/lk/paopao/dto/UserDto.java +++ b/src/main/java/com/lk/paopao/dto/UserDto.java @@ -16,6 +16,8 @@ public class UserDto implements Serializable { String phone; Byte status; String avatar; - Long balance; Boolean isAdmin; + Integer follows=0; + Integer followings=0; + Integer tweetsCount=0; } \ No newline at end of file diff --git a/src/main/resources/application.yml b/src/main/resources/application.yml index 667a55b..fb55ab6 100644 --- a/src/main/resources/application.yml +++ b/src/main/resources/application.yml @@ -3,6 +3,10 @@ springdoc: path: /api-docs spring: + + jackson: + property-naming-strategy: SNAKE_CASE # 驼峰转下划线 + datasource: url: jdbc:h2:file:./paopao.h2 # 使用文件存储 driverClassName: org.h2.Driver @@ -45,4 +49,4 @@ app: - path: "/v1/auth/**" methods: [ "GET","PUT","POST"] allowed-origins: - - "http://localhost:8080" \ No newline at end of file + - "http://localhost:5173" \ No newline at end of file