使用与配置

Constant 的静态工具无需配置。Spring 条件和属性模型仅在应用显式使用或注册时参与容器处理；模块没有统一的 own.constant.enabled 开关。

只使用集合、文件或脱敏方法时，可直接进入对应专题。需要复用常量时读“公共约定”；需要声明拦截元数据时读“元数据注解”；需要按配置创建 Bean 或注入属性时，再阅读本页最后两节。

公共约定

公共常量统一路径、时间和文件格式等约定。例如，拼接 JPEG 文件名时使用带点的 Suffix，传给图片编码器时使用不带点的 Format：

import com.own.constant.ConstantFile;

String fileName = "avatar" + ConstantFile.Suffix.JPG; // avatar.jpg
String outputFormat = ConstantFile.Format.JPEG;      // jpeg

完整的格式选择见下一小节；其他常量可按用途查下表，类型均位于 com.own.constant 包中。

公共常量速查

用途	类型与实际值
API 路径	ConstantApiPrefix.BASE_API_PREFIX="/api/"；客户端段为 admin/、app/、public/、api/
展示与模块标识	ConstantBeanSuffix 提供中文 Bean 展示后缀；ConstantModule 提供模块编码；ConstantPermission 提供“查询”“新增”等中文动作值
环境	ConstantEnvironmentType.DEV="dev"、PROD="pro"、TEST="test"、LOCALHOST="localhost"
时间长度	ConstantDuration.ONE_DAY 为一天的 Duration；ConstantTime.Millisecond 的秒、分、时、日、周常量均以毫秒计
日期格式	ConstantDateFormatPattern 提供标准带分隔符、无分隔符的 Pattern/Formatter，以及兼容的 Pattern / Formatter 命名
时长模板	ConstantDurationPattern.PatternForStandard 提供 d天h小时m分钟s秒 等模板，不是日期格式串
账号与性别	ConstantAccount.UserTypeEnum.of(1/2) 返回 NORMAL/ADMIN，其他值为 null；ConstantGender.Item 为男 1、女 2、保密 0
字符转换	ConstantConvert.STRING_TO_INTEGER 等为 JDK 解析函数；不额外裁剪空白或吞掉解析异常
数值	ConstantNumber 提供整数与 BigDecimal；TEM / BIG_DECIMAL_TEM 的实际值是 10
通用值	ConstantCommon 包括 TRACE_ID="traceId"、SUCCESS_CODE="00000"、业务错误 E0001、处理错误 E0002、请求确认 C0001
配置占位符	ConstantValue.buildConfigValueGroup("project.region-map.cn") 返回 ${own.project.region-map.cn}，不读取配置，也不校验 null
其他标识	ConstantPackage.NAME="com.own"、ConstantVersion.VERSION_1 至 VERSION_5；云厂商和请求来源由 ConstantCloudService、ConstantRequestManager 定义

ConstantStats.getFormat(key) 只接收 hour/day/month/year，返回 MySQL 风格日期格式；其他非 null 值抛 IllegalArgumentException，null 会在内部不可变 Map 查询时抛 NullPointerException。CalendarInterval 中出现 week/quarter 不代表该函数支持它们。

ConstantCommon.ADMINISTRATOR_ID_LIST 是默认空的可变 HashSet<String>，没有并发保护或自动授权行为。常量中的模块、云厂商和文件格式名称也不表示相应实现已装配。

文件格式、扩展名与后缀

当前统一使用 ConstantFile 的嵌套类型：

入口	示例	使用位置
ConstantFile.Format.JPEG	jpeg	图片编码格式
ConstantFile.Extension.JPG	jpg	不带点的文件扩展名
ConstantFile.Suffix.JPG	.jpg	拼接文件名的后缀
ConstantFile.EnumFormat.JPEG	主后缀 .jpeg，支持后缀 .jpeg、.jpg	格式描述数据
ConstantFile.Image.getEnumFormatByFormat("jpeg")	EnumFormat.JPEG	按精确格式名查询

格式查询区分大小写，不按扩展名别名归一；"jpg"、".jpg"、未知值与 null 返回 null。FileType 声明 DOCUMENT、IMAGE、RADIO、VIDEO、OTHER；当前 EnumFormat 项都归为 IMAGE，包括 PDF。它们只描述元数据，实际图片读写取决于 ImageIO 能力。

元数据注解

这些注解保留到运行期，消费它们的模块决定最终行为。只有 constant 依赖时，不会自动执行登录校验、防重、权限拦截或日志采集。

注解	位置与属性	消费边界
@DevelopAop	方法，无属性	Base 的维护拦截标记；没有 profile 条件，见 Base 行为
@ServiceInfo	类型；必填 name	服务展示元数据，可供 Base Business 读取
@SubmitAop	方法；version=0、must=true	声明提交保护参数，Constant 不实现提交保护
@LoginApiAop	方法；必填 account/type，isCheck=true	登录流程元数据，Constant 不解释表达式、不调用认证
@LoginDislodge / @LoginIgnore	前者用于方法；后者用于类型、方法	登录剔除/忽略标记，具体规则由消费者实现
@PermissionModule	类型；必填 value	声明权限模块
@PermissionOperation	类型、方法；必填 value 数组，module=""、accountType=2	可重复，由 PermissionOperations 容纳
@PermissionOperations	类型、方法；必填 value，module=""、logic=OR	可由 PermissionOperationsGroup 再分组
@PermissionRole / @PermissionRoleExcept	方法；必填角色名 value	可重复，对应容器为 PermissionRoles / PermissionRolesExcept
@AopSystemLogModule / @AopSystemLogRecord	模块与操作描述	属性及优先级见系统日志配置

通用注解位于 com.own.constant.aop，登录、权限、日志分别在其 login、permission、log 子包。多操作 AND/OR、空模块回退与账号类型过滤不能只从注解名称推断，需要以实际权限消费者为准。

ConstantSystemAopOrder 只提供历史顺序值 LOGIN_CHECK=-10、LOG_OPERATION=-11；系统日志当前使用 MVC 生命周期采集，不由这些常量自行启用切面。

按配置列表启用 Bean

@ConditionalOnPropertyOneOfArray 可用于配置类或 @Bean 方法，使用 Spring Binder 将属性绑定为 List<String>，通过 contains 精确匹配目标值。

own:
  features:
    enabled:
      - audit

在应用扫描范围中添加配置类：

package example;

import com.own.constant.aop.ConditionalOnPropertyOneOfArray;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration(proxyBeanMethods = false)
public class FeatureConfiguration {
    @Bean
    @ConditionalOnPropertyOneOfArray(
            prefix = "own.features", name = "enabled", value = "audit")
    String auditFeatureMarker() {
        return "audit-enabled";
    }
}

配置包含 audit 时容器中存在名为 auditFeatureMarker 的 Bean；不包含时不创建。prefix 默认空字符串，非空时用 . 与必填的 name 拼接；value 必填，区分大小写。属性未绑定时按 matchIfMissing（默认 false）处理，已经绑定但不包含目标值时仍为 false。绑定异常没有被捕获，不会一律降级为 matchIfMissing。

ConditionDevelop、ConditionTest 可配合 @Conditional 使用，但只比较 spring.profiles.active 的完整字符串是否等于 dev / test；dev,local 不匹配，也不会读取 active profiles 集合来判断。

属性模型注册

需要把 YAML 中的地域映射注入应用时，使用 CustomProjectProperty；需要读取日志参数模型时，使用 CustomLoggingProperty。按需注册所用类型，下面展示两者一起注册的方式。配置类须位于应用扫描范围中，或由应用显式 @Import：

package example;

import com.own.constant.property.CustomLoggingProperty;
import com.own.constant.property.CustomProjectProperty;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Configuration;

@Configuration(proxyBeanMethods = false)
@EnableConfigurationProperties({CustomProjectProperty.class, CustomLoggingProperty.class})
public class ConstantPropertiesConfiguration {
}

两种模型都带 @SpringBootConfiguration，已有扫描或显式注册时不要重复注册。普通应用保持自己的扫描范围即可，无需扫描整个 com.own。

完整属性	类型	模型默认值
own.project.region-map	Map<String,String>	null
logging.logback.rollingpolicy.max-file-size	DataSize	10MB
logging.logback.rollingpolicy.file-name-pattern	String	空字符串
logging.logback.rollingpolicy.max-history	Integer	7
logging.logback.rollingpolicy.logstash-uri	String	空字符串

own:
  project:
    region-map:
      cn: cn-north-1
logging:
  logback:
    rollingpolicy:
      max-file-size: 50MB
      max-history: 30

绑定后，通过构造器注入 CustomProjectProperty 并调用 getRegionMap().get("cn")，应得到 cn-north-1；注入 CustomLoggingProperty 后，最大历史数应为 30。删除 own.project.region-map 配置后对应 Map 为 null，读取前需判空。

这些值是属性对象的初始值，没有额外字段校验；new 出来的对象不会自动绑定环境。CustomProjectProperty 不会选择云服务地域，CustomLoggingProperty 也不负责创建 Appender、滚动文件或连接 Logstash；这些行为需要实际消费者或日志配置。