From bdd6e61160e54269e676d75ed07499276dc030c2 Mon Sep 17 00:00:00 2001 From: ZhouXY108 Date: Fri, 21 Feb 2025 21:50:18 +0800 Subject: [PATCH] =?UTF-8?q?=E8=A1=A5=E5=85=85=E5=90=84=E5=8C=85=E7=9A=84?= =?UTF-8?q?=20javadoc?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 在每个包下都创建 package-info.java 文件，编写 javadoc，对每个包进行说明。 --- .../commons/annotation/package-info.java | 64 +++++++++ .../plusone/commons/base/package-info.java | 10 +- .../commons/collection/package-info.java | 27 ++++ .../commons/constant/package-info.java | 29 ++++ .../exception/business/package-info.java | 22 +++ .../commons/exception/package-info.java | 129 ++++++++++++++++++ .../exception/system/package-info.java | 22 +++ .../commons/function/package-info.java | 10 +- .../commons/model/dto/package-info.java | 66 +++++++++ .../plusone/commons/model/package-info.java | 25 ++++ .../plusone/commons/time/package-info.java | 27 ++++ .../plusone/commons/util/package-info.java | 25 ++++ 12 files changed, 448 insertions(+), 8 deletions(-) create mode 100644 src/main/java/xyz/zhouxy/plusone/commons/annotation/package-info.java create mode 100644 src/main/java/xyz/zhouxy/plusone/commons/collection/package-info.java create mode 100644 src/main/java/xyz/zhouxy/plusone/commons/constant/package-info.java create mode 100644 src/main/java/xyz/zhouxy/plusone/commons/exception/business/package-info.java create mode 100644 src/main/java/xyz/zhouxy/plusone/commons/exception/package-info.java create mode 100644 src/main/java/xyz/zhouxy/plusone/commons/exception/system/package-info.java create mode 100644 src/main/java/xyz/zhouxy/plusone/commons/model/dto/package-info.java create mode 100644 src/main/java/xyz/zhouxy/plusone/commons/model/package-info.java create mode 100644 src/main/java/xyz/zhouxy/plusone/commons/time/package-info.java create mode 100644 src/main/java/xyz/zhouxy/plusone/commons/util/package-info.java diff --git a/src/main/java/xyz/zhouxy/plusone/commons/annotation/package-info.java b/src/main/java/xyz/zhouxy/plusone/commons/annotation/package-info.java new file mode 100644 index 0000000..f3a994c --- /dev/null +++ b/src/main/java/xyz/zhouxy/plusone/commons/annotation/package-info.java @@ -0,0 +1,64 @@ +/* + * Copyright 2025 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + *

注解

+ * + *

+ * 1. {@link StaticFactoryMethod} + *

+ *

+ * 标识静态工厂方法。 + * 《Effective Java》的 Item1 建议考虑用静态工厂方法替换构造器， + * 因而考虑有一个注解可以标记一下静态工厂方法，以和其它方法进行区分。 + *

+ * + *

+ * 2. {@link ReaderMethod} 和 {@link WriterMethod} + *

+ *

+ * 分别标识读方法（如 getter）或写方法（如 setter）。 + *

+ *

+ * 最早是写了一个集合类，为了方便判断使用读写锁时，哪些情况下使用读锁，哪些情况下使用写锁。 + *

+ * + *

+ * 3. {@link UnsupportedOperation} + *

+ *

+ * 标识该方法不被支持或没有实现，将抛出 {@link UnsupportedOperationException}。 + * 为了方便在使用时，不需要点进源码，就能知道该方法没有实现。 + *

+ * + *

+ * 4. {@link Virtual} + *

+ *

+ * Java 非 final 的实例方法，对应 C++/C# 中的虚方法，允许被子类覆写。 + * {@link Virtual} 注解旨在设计父类时，强调该方法父类虽然有默认实现，但子类可以根据自己的需要覆写。 + *

+ * + *

+ * 5. {@link ValueObject} + *

+ *

+ * 标记一个类，表示其作为值对象，区别与 Entity。 + *

+ * + * @author ZhouXY + */ +package xyz.zhouxy.plusone.commons.annotation; diff --git a/src/main/java/xyz/zhouxy/plusone/commons/base/package-info.java b/src/main/java/xyz/zhouxy/plusone/commons/base/package-info.java index 523b74d..43dff12 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/base/package-info.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/base/package-info.java @@ -15,9 +15,9 @@ */ /** - * 基础组件 + *

基础组件

* - *

Ref

+ *

1. Ref

*

* {@link Ref} 包装了一个值，表示对该值的应用。 *

@@ -61,11 +61,13 @@ * System.out.println(result); // Output: Return string * * - *

IWithCode

+ *

2. IWithCode

*

- * 类似于枚举之类的类，通常需要设置固定的码值表示对应的含义。 + * 类似于枚举这样的类型，通常需要设置固定的码值表示对应的含义。 * 可实现 {@link IWithCode}、{@link IWithIntCode}、{@link IWithLongCode}，便于在需要的地方对这些接口的实现进行处理。 *

+ * + * @author ZhouXY */ @CheckReturnValue @ParametersAreNonnullByDefault diff --git a/src/main/java/xyz/zhouxy/plusone/commons/collection/package-info.java b/src/main/java/xyz/zhouxy/plusone/commons/collection/package-info.java new file mode 100644 index 0000000..4467e60 --- /dev/null +++ b/src/main/java/xyz/zhouxy/plusone/commons/collection/package-info.java @@ -0,0 +1,27 @@ +/* + * Copyright 2025 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + *

集合

+ * + *

+ * 1. {@link CollectionTools} + *

+ * 集合工具类 + * + * @author ZhouXY + */ +package xyz.zhouxy.plusone.commons.collection; diff --git a/src/main/java/xyz/zhouxy/plusone/commons/constant/package-info.java b/src/main/java/xyz/zhouxy/plusone/commons/constant/package-info.java new file mode 100644 index 0000000..8e52806 --- /dev/null +++ b/src/main/java/xyz/zhouxy/plusone/commons/constant/package-info.java @@ -0,0 +1,29 @@ +/* + * Copyright 2025 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + *

常量

+ * + *

+ * 1. 正则常量 + *

+ * {@link RegexConsts} 包含常见正则表达式；{@link PatternConsts} 包含对应的 {@link Pattern} 对象。 + * + * @author ZhouXY + */ +package xyz.zhouxy.plusone.commons.constant; + +import java.util.regex.Pattern; diff --git a/src/main/java/xyz/zhouxy/plusone/commons/exception/business/package-info.java b/src/main/java/xyz/zhouxy/plusone/commons/exception/business/package-info.java new file mode 100644 index 0000000..baa23b5 --- /dev/null +++ b/src/main/java/xyz/zhouxy/plusone/commons/exception/business/package-info.java @@ -0,0 +1,22 @@ +/* + * Copyright 2025 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * 业务异常 + * + * @author ZhouXY + */ +package xyz.zhouxy.plusone.commons.exception.business; diff --git a/src/main/java/xyz/zhouxy/plusone/commons/exception/package-info.java b/src/main/java/xyz/zhouxy/plusone/commons/exception/package-info.java new file mode 100644 index 0000000..6b63078 --- /dev/null +++ b/src/main/java/xyz/zhouxy/plusone/commons/exception/package-info.java @@ -0,0 +1,129 @@ +/* + * Copyright 2025 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + *

异常

+ * + *

1. {@link MultiTypesException} - 多类型异常

+ *

+ * 异常在不同场景下被抛出，可以用不同的枚举值，表示不同的场景类型。 + *

+ *

+ * 异常实现 {@link MultiTypesException} 的 {@link MultiTypesException#getType} 方法，返回对应的场景类型。 + *

+ *

+ * 表示场景类型的枚举实现 {@link MultiTypesException.ExceptionType}，其中的工厂方法用于创建类型对象。 + *

+ * + * 
+ * public final class LoginException
+ *         extends RuntimeException
+ *         implements MultiTypesException<LoginException, LoginException.Type> {
+ *     private final Type type;
+ *     private LoginException(@Nonnull Type type, @Nonnull String message) {
+ *         super(message);
+ *         this.type = type;
+ *     }
+ *
+ *     private LoginException(@Nonnull Type type, @Nonnull Throwable cause) {
+ *         super(cause);
+ *         this.type = type;
+ *     }
+ *
+ *     private LoginException(@Nonnull Type type,
+ *                            @Nonnull String message,
+ *                            @Nonnull Throwable cause) {
+ *         super(message, cause);
+ *         this.type = type;
+ *     }
+ *
+ *     @Override
+ *     public @Nonnull Type getType() {
+ *         return this.type;
+ *     }
+ *
+ *     // ...
+ *
+ *     public enum Type implements ExceptionType {
+ *         DEFAULT("00", "当前会话未登录"),
+ *         NOT_TOKEN("10", "未提供token"),
+ *         INVALID_TOKEN("20", "token无效"),
+ *         TOKEN_TIMEOUT("30", "token已过期"),
+ *         BE_REPLACED("40", "token已被顶下线"),
+ *         KICK_OUT("50", "token已被踢下线"),
+ *         ;
+ *
+ *         @Nonnull
+ *         private final String code;
+ *         @Nonnull
+ *         private final String defaultMessage;
+ *
+ *         Type(@Nonnull String code, @Nonnull String defaultMessage) {
+ *             this.code = code;
+ *             this.defaultMessage = defaultMessage;
+ *         }
+ *
+ *         @Override
+ *         public @Nonnull String getCode() {
+ *             return code;
+ *         }
+ *
+ *         @Override
+ *         public @Nonnull String getDefaultMessage() {
+ *             return defaultMessage;
+ *         }
+ *
+ *         @Override
+ *         public @Nonnull LoginException create() {
+ *             return new LoginException(this, this.defaultMessage);
+ *         }
+ *
+ *         @Override
+ *         public @Nonnull LoginException create(String message) {
+ *             return new LoginException(this, message);
+ *         }
+ *
+ *         @Override
+ *         public @Nonnull LoginException create(Throwable cause) {
+ *             return new LoginException(this, cause);
+ *         }
+ *
+ *         @Override
+ *         public @Nonnull LoginException create(String message, Throwable cause) {
+ *             return new LoginException(this, message, cause);
+ *         }
+ *     }
+ * }
+ *
+ * + * 使用时，可以使用这种方式创建并抛出异常： + * 
+ * throw LoginException.Type.TOKEN_TIMEOUT.create();
+ *
+ *

+ * + *

2. 业务异常

+ * 预设常见的业务异常。可继承 {@link BizException} 自定义业务异常。 + * + *

3. 系统异常

+ * 预设常见的系统异常。可继承 {@link SysException} 自定义系统异常。 + * + * @author ZhouXY + */ +package xyz.zhouxy.plusone.commons.exception; + +import xyz.zhouxy.plusone.commons.exception.business.*; +import xyz.zhouxy.plusone.commons.exception.system.*; diff --git a/src/main/java/xyz/zhouxy/plusone/commons/exception/system/package-info.java b/src/main/java/xyz/zhouxy/plusone/commons/exception/system/package-info.java new file mode 100644 index 0000000..c44c0ae --- /dev/null +++ b/src/main/java/xyz/zhouxy/plusone/commons/exception/system/package-info.java @@ -0,0 +1,22 @@ +/* + * Copyright 2025 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * 系统异常 + * + * @author ZhouXY + */ +package xyz.zhouxy.plusone.commons.exception.system; diff --git a/src/main/java/xyz/zhouxy/plusone/commons/function/package-info.java b/src/main/java/xyz/zhouxy/plusone/commons/function/package-info.java index 2c731f4..458a666 100644 --- a/src/main/java/xyz/zhouxy/plusone/commons/function/package-info.java +++ b/src/main/java/xyz/zhouxy/plusone/commons/function/package-info.java @@ -15,16 +15,16 @@ */ /** - * 函数式编程 + *

函数式编程

* - *

PredicateTools

+ *

1. PredicateTools

*

* {@link PredicateTools} 用于 {@link java.util.function.Predicate} 的相关操作。 *

* - *

Functional interfaces

+ *

2. Functional interfaces

*

- * 补充一些 JDK 没有，而项目中可能用得上的函数式接口： + * 补充可能用得上的函数式接口： * 

  * | Group         | FunctionalInterface  | method                           |
  * | ------------- | -------------------- | -------------------------------- |
@@ -40,5 +40,7 @@
  * | Optional      | ToOptionalFunction   | Optional<R> apply(T)             |
  *
*

+ * + * @author ZhouXY */ package xyz.zhouxy.plusone.commons.function; diff --git a/src/main/java/xyz/zhouxy/plusone/commons/model/dto/package-info.java b/src/main/java/xyz/zhouxy/plusone/commons/model/dto/package-info.java new file mode 100644 index 0000000..016bbf1 --- /dev/null +++ b/src/main/java/xyz/zhouxy/plusone/commons/model/dto/package-info.java @@ -0,0 +1,66 @@ +/* + * Copyright 2025 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + *

数据传输对象

+ * + *

1. 分页

+ *

+ * 分页组件由 {@link PagingAndSortingQueryParams} 作为入参， + * 因为分页必须伴随着排序，不然可能出现同一个对象重复出现在不同页，有的对象不被查询到的情况， + * 所以分页查询的入参必须包含排序条件。 + *

+ *

+ * 用户可继承 {@link PagingAndSortingQueryParams} + * 构建自己的分页查询入参，需在构造器中调用 {@link PagingAndSortingQueryParams} 的构造器，传入一个 Map 作为白名单， + * key 是供前端指定用于排序的属性名，value 是对应数据库中的字段名，只有在白名单中指定的属性名才允许作为排序条件。 + *

+ *

+ * {@link PagingAndSortingQueryParams} 包含三个主要的属性： + *

+ * 其中 orderBy 是一个 List，可以指定多个排序条件，每个排序条件是一个字符串， + * 格式为“属性名-ASC”或“属性名-DESC”，分别表示升序和降序。 + *

+ *

+ * 比如前端传入的 orderBy 为 ["name-ASC","age-DESC"]，意味着要按 name 进行升序，name 相同的情况下则按 age 进行降序。 + *

+ *

+ * 使用时调用 {@link PagingAndSortingQueryParams#buildPagingParams()} 方法获取分页参数 {@link PagingParams}。 + *

+ *

+ * 分页结果可以存放到 {@link PageResult} 中，作为出参。 + *

+ * + *

2. {@link UnifiedResponse}

+ *

+ * {@link UnifiedResponse} 对返回给前端的数据进行封装，包含 code、message、data。 + *

+ *

+ * 可使用 {@link UnifiedResponses} 快速构建 {@link UnifiedResponse} 对象。 + * {@link UnifiedResponses} 默认的成功代码为 "2000000"， + * 用户按测试类 CustomUnifiedResponseFactoryTests 中所示范的，继承 {@link UnifiedResponses} + * 实现自己的工厂类， + * 自定义 SUCCESS_CODE 和 DEFAULT_SUCCESS_MSG 和工厂方法。 + * 见 issue#22。 + *

+ * + * @author ZhouXY + */ +package xyz.zhouxy.plusone.commons.model.dto; diff --git a/src/main/java/xyz/zhouxy/plusone/commons/model/package-info.java b/src/main/java/xyz/zhouxy/plusone/commons/model/package-info.java new file mode 100644 index 0000000..d3112a9 --- /dev/null +++ b/src/main/java/xyz/zhouxy/plusone/commons/model/package-info.java @@ -0,0 +1,25 @@ +/* + * Copyright 2025 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + *

业务建模组件

+ *

+ * 包含业务建模可能用到的性别、身份证等元素，也包含 DTO 相关类，如分页查询参数，响应结果，分页结果等。 + *

+ * + * @author ZhouXY + */ +package xyz.zhouxy.plusone.commons.model; diff --git a/src/main/java/xyz/zhouxy/plusone/commons/time/package-info.java b/src/main/java/xyz/zhouxy/plusone/commons/time/package-info.java new file mode 100644 index 0000000..600b2a0 --- /dev/null +++ b/src/main/java/xyz/zhouxy/plusone/commons/time/package-info.java @@ -0,0 +1,27 @@ +/* + * Copyright 2025 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + *

时间 API

+ * + *

1. 季度 API

+ * + * 模仿 JDK 的 {@link java.time.Month} 和 {@link java.time.YearMonth}， + * 实现 {@link Quarter}，{@link YearQuarter}，对季度进行建模。 + * + * @author ZhouXY + */ +package xyz.zhouxy.plusone.commons.time; diff --git a/src/main/java/xyz/zhouxy/plusone/commons/util/package-info.java b/src/main/java/xyz/zhouxy/plusone/commons/util/package-info.java new file mode 100644 index 0000000..a5bb28e --- /dev/null +++ b/src/main/java/xyz/zhouxy/plusone/commons/util/package-info.java @@ -0,0 +1,25 @@ +/* + * Copyright 2025 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + *

工具类

+ *

+ * 包含树构建器（{@link TreeBuilder}）、断言工具（{@link AssertTools}）、ID 生成器（{@link IdGenerator}）及其它实用工具类。 + *

+ * + * @author ZhouXY + */ +package xyz.zhouxy.plusone.commons.util;