+ * 标识静态工厂方法。 + * 《Effective Java》的 Item1 建议考虑用静态工厂方法替换构造器， + * 因而考虑有一个注解可以标记一下静态工厂方法，以和其它方法进行区分。 + *
+ * + *+ * 分别标识读方法（如 getter）或写方法（如 setter）。 + *
+ *+ * 最早是写了一个集合类，为了方便判断使用读写锁时，哪些情况下使用读锁，哪些情况下使用写锁。 + *
+ * + *+ * 标识该方法不被支持或没有实现，将抛出 {@link UnsupportedOperationException}。 + * 为了方便在使用时，不需要点进源码，就能知道该方法没有实现。 + *
+ * + *+ * Java 非 final 的实例方法，对应 C++/C# 中的虚方法，允许被子类覆写。 + * {@link Virtual} 注解旨在设计父类时，强调该方法父类虽然有默认实现，但子类可以根据自己的需要覆写。 + *
+ * + *+ * 标记一个类，表示其作为值对象，区别与 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 @@ */ /** - * 基础组件 + ** {@link Ref} 包装了一个值，表示对该值的应用。 *
@@ -61,11 +61,13 @@ * System.out.println(result); // Output: Return string * * - *- * 类似于枚举之类的类，通常需要设置固定的码值表示对应的含义。 + * 类似于枚举这样的类型，通常需要设置固定的码值表示对应的含义。 * 可实现 {@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. + */ + +/** + *+ * 异常在不同场景下被抛出，可以用不同的枚举值，表示不同的场景类型。 + *
+ *+ * 异常实现 {@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(); + *+ * + * + *
* {@link PredicateTools} 用于 {@link java.util.function.Predicate} 的相关操作。 *
* - *- * 补充一些 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. + */ + +/** + *
+ * 分页组件由 {@link PagingAndSortingQueryParams} 作为入参， + * 因为分页必须伴随着排序，不然可能出现同一个对象重复出现在不同页，有的对象不被查询到的情况， + * 所以分页查询的入参必须包含排序条件。 + *
+ *+ * 用户可继承 {@link PagingAndSortingQueryParams} + * 构建自己的分页查询入参，需在构造器中调用 {@link PagingAndSortingQueryParams} 的构造器，传入一个 Map 作为白名单， + * key 是供前端指定用于排序的属性名，value 是对应数据库中的字段名，只有在白名单中指定的属性名才允许作为排序条件。 + *
+ *+ * {@link PagingAndSortingQueryParams} 包含三个主要的属性： + *
+ * 比如前端传入的 orderBy 为 ["name-ASC","age-DESC"]，意味着要按 name 进行升序，name 相同的情况下则按 age 进行降序。 + *
+ *+ * 使用时调用 {@link PagingAndSortingQueryParams#buildPagingParams()} 方法获取分页参数 {@link PagingParams}。 + *
+ *+ * 分页结果可以存放到 {@link PageResult} 中，作为出参。 + *
+ * + *+ * {@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. + */ + +/** + *+ * 包含树构建器（{@link TreeBuilder}）、断言工具（{@link AssertTools}）、ID 生成器（{@link IdGenerator}）及其它实用工具类。 + *
+ * + * @author ZhouXY + */ +package xyz.zhouxy.plusone.commons.util;