补充各包的 javadoc
在每个包下都创建 package-info.java 文件，编写 javadoc，对每个包进行说明。
This commit is contained in:
parent
f024a08dd2
commit
bdd6e61160
@ -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;
|
||||
@ -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
|
||||
|
||||
@ -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;
|
||||
@ -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;
|
||||
@ -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;
|
||||
@ -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<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<LoginException> {
|
||||
* 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);
|
||||
* }
|
||||
* }
|
||||
* }
|
||||
* </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.*;
|
||||
@ -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;
|
||||
@ -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<R> apply(T) |
|
||||
* </pre>
|
||||
* </p>
|
||||
*
|
||||
* @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
|
||||
*/
|
||||
package xyz.zhouxy.plusone.commons.function;
|
||||
|
||||
@ -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;
|
||||
@ -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;
|
||||
@ -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;
|
||||
@ -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;
|
||||
Loading…
x
Reference in New Issue
Block a user