ZhouXY108/plusone-commons
1
0
Fork 0
forked from plusone/plusone-commons
Code Issues Pull Requests Activity

补充各包的 javadoc

Browse Source 
在每个包下都创建 package-info.java 文件，编写 javadoc，对每个包进行说明。
This commit is contained in:
zhouxy108 2025-02-21 21:50:18 +08:00
parent f024a08dd2
commit bdd6e61160
12 changed files with 448 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
src/main/java/xyz/zhouxy/plusone/commons/annotation/package-info.java Normal file
View File

@ -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.
*/
/**
* <h2>注解</h2>
*
* <h3>
* 1. {@link StaticFactoryMethod}
* </h3>
* <p>
* 标识<b>静态工厂方法</b>。
* 《Effective Java》的 Item1 建议考虑用静态工厂方法替换构造器，
* 因而考虑有一个注解可以标记一下静态工厂方法，以和其它方法进行区分。
* </p>
*
* <h3>
* 2. {@link ReaderMethod} 和 {@link WriterMethod}
* </h3>
* <p>
* 分别标识<b>读方法</b>（如 getter）或<b>写方法</b>（如 setter）。
* </p>
* <p>
* 最早是写了一个集合类，为了方便判断使用读写锁时，哪些情况下使用读锁，哪些情况下使用写锁。
* </p>
*
* <h3>
* 3. {@link UnsupportedOperation}
* </h3>
* <p>
* 标识该方法不被支持或没有实现，将抛出 {@link UnsupportedOperationException}。
* 为了方便在使用时，不需要点进源码，就能知道该方法没有实现。
* </p>
*
* <h3>
* 4. {@link Virtual}
* </h3>
* <p>
* Java 非 final 的实例方法，对应 C++/C# 中的虚方法，允许被子类覆写。
* {@link Virtual} 注解旨在设计父类时，强调该方法父类虽然有默认实现，但子类可以根据自己的需要覆写。
* </p>
*
* <h3>
* 5. {@link ValueObject}
* </h3>
* <p>
* 标记一个类，表示其作为值对象，区别与 Entity。
* </p>
*
* @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
*/
package xyz.zhouxy.plusone.commons.annotation;

10
src/main/java/xyz/zhouxy/plusone/commons/base/package-info.java
View File

@ -15,9 +15,9 @@
*/
/**
* 基础组件
* <h2>基础组件</h2>
*
* <h2>Ref</h2>
* <h3>1. Ref</h3>
* <p>
* {@link Ref} 包装了一个值，表示对该值的应用。
* </p>
@ -61,11 +61,13 @@
* System.out.println(result); // Output: Return string
* </pre>
*
* <h2>IWithCode</h2>
* <h3>2. IWithCode</h3>
* <p>
* 类似于枚举之类的类，通常需要设置固定的码值表示对应的含义。
* 类似于枚举这样的类型，通常需要设置固定的码值表示对应的含义。
* 可实现 {@link IWithCode}、{@link IWithIntCode}、{@link IWithLongCode}，便于在需要的地方对这些接口的实现进行处理。
* </p>
*
* @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
*/
@CheckReturnValue
@ParametersAreNonnullByDefault

27
src/main/java/xyz/zhouxy/plusone/commons/collection/package-info.java Normal file
View File

@ -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.
*/
/**
* <h2>集合<h2>
*
* <h3>
* 1. {@link CollectionTools}
* </h3>
* 集合工具类
*
* @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
*/
package xyz.zhouxy.plusone.commons.collection;

29
src/main/java/xyz/zhouxy/plusone/commons/constant/package-info.java Normal file
View File

@ -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.
*/
/**
* <h2>常量<h2>
*
* <h3>
* 1. 正则常量
* </h3>
* {@link RegexConsts} 包含常见正则表达式；{@link PatternConsts} 包含对应的 {@link Pattern} 对象。
*
* @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
*/
package xyz.zhouxy.plusone.commons.constant;
import java.util.regex.Pattern;

22
src/main/java/xyz/zhouxy/plusone/commons/exception/business/package-info.java Normal file
View File

@ -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 <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
*/
package xyz.zhouxy.plusone.commons.exception.business;

129
src/main/java/xyz/zhouxy/plusone/commons/exception/package-info.java Normal file
View File

@ -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.
*/
/**
* <h2>异常<h2>
*
* <h3>1. {@link MultiTypesException} - 多类型异常</h3>
* <p>
* 异常在不同场景下被抛出，可以用不同的枚举值，表示不同的场景类型。
* </p>
* <p>
* 异常实现 {@link MultiTypesException} 的 {@link MultiTypesException#getType} 方法，返回对应的场景类型。
* </p>
* <p>
* 表示场景类型的枚举实现 {@link MultiTypesException.ExceptionType}，其中的工厂方法用于创建类型对象。
* </p>
*
* <pre>
* public final class LoginException
* extends RuntimeException
* implements MultiTypesException&lt;LoginException, LoginException.Type&gt; {
* private final Type type;
* private LoginException(&#64;Nonnull Type type, &#64;Nonnull String message) {
* super(message);
* this.type = type;
* }
*
* private LoginException(&#64;Nonnull Type type, &#64;Nonnull Throwable cause) {
* super(cause);
* this.type = type;
* }
*
* private LoginException(&#64;Nonnull Type type,
* &#64;Nonnull String message,
* &#64;Nonnull Throwable cause) {
* super(message, cause);
* this.type = type;
* }
*
* &#64;Override
* public &#64;Nonnull Type getType() {
* return this.type;
* }
*
* // ...
*
* public enum Type implements ExceptionType<LoginException> {
* DEFAULT("00", "当前会话未登录"),
* NOT_TOKEN("10", "未提供token"),
* INVALID_TOKEN("20", "token无效"),
* TOKEN_TIMEOUT("30", "token已过期"),
* BE_REPLACED("40", "token已被顶下线"),
* KICK_OUT("50", "token已被踢下线"),
* ;
*
* &#64;Nonnull
* private final String code;
* &#64;Nonnull
* private final String defaultMessage;
*
* Type(&#64;Nonnull String code, &#64;Nonnull String defaultMessage) {
* this.code = code;
* this.defaultMessage = defaultMessage;
* }
*
* &#64;Override
* public &#64;Nonnull String getCode() {
* return code;
* }
*
* &#64;Override
* public &#64;Nonnull String getDefaultMessage() {
* return defaultMessage;
* }
*
* &#64;Override
* public &#64;Nonnull LoginException create() {
* return new LoginException(this, this.defaultMessage);
* }
*
* &#64;Override
* public &#64;Nonnull LoginException create(String message) {
* return new LoginException(this, message);
* }
*
* &#64;Override
* public &#64;Nonnull LoginException create(Throwable cause) {
* return new LoginException(this, cause);
* }
*
* &#64;Override
* public &#64;Nonnull LoginException create(String message, Throwable cause) {
* return new LoginException(this, message, cause);
* }
* }
* }
* </pre>
*
* 使用时，可以使用这种方式创建并抛出异常：
* <pre>
* throw LoginException.Type.TOKEN_TIMEOUT.create();
* </pre>
* </p>
*
* <h3>2. 业务异常</h3>
* 预设常见的业务异常。可继承 {@link BizException} 自定义业务异常。
*
* <h3>3. 系统异常</h3>
* 预设常见的系统异常。可继承 {@link SysException} 自定义系统异常。
*
* @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
*/
package xyz.zhouxy.plusone.commons.exception;
import xyz.zhouxy.plusone.commons.exception.business.*;
import xyz.zhouxy.plusone.commons.exception.system.*;

22
src/main/java/xyz/zhouxy/plusone/commons/exception/system/package-info.java Normal file
View File

@ -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 <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
*/
package xyz.zhouxy.plusone.commons.exception.system;

10
src/main/java/xyz/zhouxy/plusone/commons/function/package-info.java
View File

@ -15,16 +15,16 @@
*/
/**
* 函数式编程
* <h2>函数式编程</h2>
*
* <h2>PredicateTools</h2>
* <h3>1. PredicateTools</h3>
* <p>
* {@link PredicateTools} 用于 {@link java.util.function.Predicate} 的相关操作。
* </p>
*
* <h2>Functional interfaces</h2>
* <h3>2. Functional interfaces</h3>
* <p>
* 补充一些 JDK 没有，而项目中可能用得上的函数式接口：
* 补充可能用得上的函数式接口：
* <pre>
* | Group | FunctionalInterface | method |
* | ------------- | -------------------- | -------------------------------- |
@ -40,5 +40,7 @@
* | Optional | ToOptionalFunction | Optional&lt;R&gt; apply(T) |
* </pre>
* </p>
*
* @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
*/
package xyz.zhouxy.plusone.commons.function;

66
src/main/java/xyz/zhouxy/plusone/commons/model/dto/package-info.java Normal file
View File

@ -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.
*/
/**
* <h2>数据传输对象</h2>
*
* <h3>1. 分页</h3>
* <p>
* 分页组件由 {@link PagingAndSortingQueryParams} 作为入参，
* 因为分页必须伴随着排序，不然可能出现同一个对象重复出现在不同页，有的对象不被查询到的情况，
* 所以分页查询的入参必须包含排序条件。
* </p>
* <p>
* 用户可继承 {@link PagingAndSortingQueryParams}
* 构建自己的分页查询入参，需在构造器中调用 {@link PagingAndSortingQueryParams} 的构造器，传入一个 Map 作为白名单，
* key 是供前端指定用于排序的属性名，value 是对应数据库中的字段名，只有在白名单中指定的属性名才允许作为排序条件。
* </p>
* <p>
* {@link PagingAndSortingQueryParams} 包含三个主要的属性：
* <ul>
* <li>size - 每页显示的记录数</li>
* <li>pageNum - 当前页码</li>
* <li>orderBy - 排序条件</li>
* </ul>
* 其中 orderBy 是一个 List，可以指定多个排序条件，每个排序条件是一个字符串，
* 格式为“属性名-ASC”或“属性名-DESC”，分别表示升序和降序。
* </p>
* <p>
* 比如前端传入的 orderBy 为 ["name-ASC","age-DESC"]，意味着要按 name 进行升序，name 相同的情况下则按 age 进行降序。
* </p>
* <p>
* 使用时调用 {@link PagingAndSortingQueryParams#buildPagingParams()} 方法获取分页参数 {@link PagingParams}。
* </p>
* <p>
* 分页结果可以存放到 {@link PageResult} 中，作为出参。
* </p>
*
* <h3>2. {@link UnifiedResponse}</h3>
* <p>
* {@link UnifiedResponse} 对返回给前端的数据进行封装，包含 code、message、data。
* </p>
* <p>
* 可使用 {@link UnifiedResponses} 快速构建 {@link UnifiedResponse} 对象。
* {@link UnifiedResponses} 默认的成功代码为 "2000000"，
* 用户按测试类 CustomUnifiedResponseFactoryTests 中所示范的，继承 {@link UnifiedResponses}
* 实现自己的工厂类，
* 自定义 SUCCESS_CODE 和 DEFAULT_SUCCESS_MSG 和工厂方法。
* 见 <a href="http://zhouxy.xyz:3000/plusone/plusone-commons/issues/22">issue#22</a>。
* </p>
*
* @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
*/
package xyz.zhouxy.plusone.commons.model.dto;

25
src/main/java/xyz/zhouxy/plusone/commons/model/package-info.java Normal file
View File

@ -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.
*/
/**
* <h2>业务建模组件</h2>
* <p>
* 包含业务建模可能用到的性别、身份证等元素，也包含 DTO 相关类，如分页查询参数，响应结果，分页结果等。
* </p>
*
* @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
*/
package xyz.zhouxy.plusone.commons.model;

27
src/main/java/xyz/zhouxy/plusone/commons/time/package-info.java Normal file
View File

@ -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.
*/
/**
* <h2>时间 API<h2>
*
* <h3>1. 季度 API</h3>
*
* 模仿 JDK 的 {@link java.time.Month} 和 {@link java.time.YearMonth}，
* 实现 {@link Quarter}，{@link YearQuarter}，对季度进行建模。
*
* @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
*/
package xyz.zhouxy.plusone.commons.time;

25
src/main/java/xyz/zhouxy/plusone/commons/util/package-info.java Normal file
View File

@ -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.
*/
/**
* <h2>工具类</h2>
* <p>
* 包含树构建器（{@link TreeBuilder}）、断言工具（{@link AssertTools}）、ID 生成器（{@link IdGenerator}）及其它实用工具类。
* </p>
*
* @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
*/
package xyz.zhouxy.plusone.commons.util;