ZhonTai Admin Core 自定义特性

命名空间：ZhonTai.Admin.Core.Attributes

中台 Admin 提供了丰富的自定义特性，用于声明式控制事务、权限、DI 生命周期、数据生成等行为。

1. 事务特性

声明式事务，通过 AOP 拦截自动管理事务。

[Transaction]

[Transaction]
public async Task CreateOrder(OrderEntity order)
{
    await _orderRepo.InsertAsync(order);
    await _stockRepo.UpdateAsync(...);
    // 异常时自动回滚
}

[AdminTransaction]

继承 Transaction，默认使用 DbKeys.AdminDb（权限库）。

[AdminTransaction]
public async Task UpdatePermission(...)
{
}

参数说明

参数	类型	默认值	说明
`Propagation`	`Propagation`	`Required`	事务传播方式
`IsolationLevel`	`IsolationLevel`	-	隔离级别
`DbKey`	`string`	-	指定数据库

⚠️ WARNING: 需要在 appconfig.json 中开启 Aop.Transaction = true 才能生效。

2. 权限与访问特性

标记登录接口，跳过权限验证但仍需 JWT 认证。

[Login]
public async Taskiresultoutput<tokeninfo> Login(LoginInput input)
{
}

[ValidatePermission]

标记需要登录+权限验证的接口（默认行为，通常无需显式添加）。

[ApiAccess]

接口级访问控制，限定可访问的操作按钮唯一编码。

[ApiAccess(All = false, Codes = new[] { "api:admin:module:delete", "api:admin:module:batchdelete" })]
public async Task Delete(long id)
{
}

参数	说明
`All`	默认`false`，`true` = 全部编码满足可访问，`false` = 满足任意一个编码可访问
`Codes`	允许访问的编码列表

[NoOperationLog]

禁用该接口的操作日志记录。

[NoOperationLog]
public async Taskiresultoutput Ping()
{
}

3. 数据库特性

[Database]

标记实体所属数据库（多库场景）。

[Database("LogDb")]
public class LogEntity : EntityBase
{
}

[AdminTransaction]

事务使用指定库，见上方事务特性。

4. DI 生命周期特性

用于控制自动注册到 IOC 容器的生命周期。

生命周期特性

[InjectSingleton]
public class MyCacheService
{
}

[InjectScoped]
public class MyService
{
}

[InjectTransient]
public class MyTool
{
}

[NonRegisterIOC]

排除自动 IOC 注册，需手动注册。

[NonRegisterIOC]
public class MyCustomService
{
}

5. ID 生成特性

[Snowflake]

主键使用雪花算法自动生成（已内置在 Entity.Id 上）。

❄ 优化的雪花算法（雪花漂移），它生成的ID更短、速度更快。
❄ 支持 k8s 等容器环境自动扩容（自动注册 WorkerId），可在单机或分布式环境生成数字型唯一ID。
❄ 如果ID生成需求不超过5W个/s，不用修改任何配置参数
❄ 如果超过5W个/s，低于50W个/s，推荐修改：SeqBitLength=10
❄ 如果超过50W个/s，接近500W个/s，推荐修改：SeqBitLength=12

1 2	[Snowflake] public long Id { get; set; }

[OrderGuid]

主键使用有序 Guid（兼顾全局唯一性与索引性能的设计）。

适用场景

分布式系统：无中央序列发生器，各节点独立生成 ID，合并数据不必担心冲突
水平分库分表：Merge、Sharding 时无需担心主键重复
对外暴露 ID：需避免被遍历的安全需求（不像自增数字可猜测）
无外部依赖：不希望依赖数据库自增、Redis 计数器等外部服务

1 2	[OrderGuid] public Guid Id { get; set; }

6. 时间特性

[ServerTime]

插入或更新时自动赋值服务器时间。

// 插入时自动赋值
[ServerTime]
public DateTime? CreatedTime { get; set; }

// 仅更新时自动赋值
[ServerTime(CanInsert = false, CanUpdate = true)]
public DateTime? ModifiedTime { get; set; }

7. API 分组与路由

[ApiGroup]

Swagger 接口分组。

[ApiGroup("订单管理")]
public class OrderService
{
}

// 不参与分组
[ApiGroup(NonGroup = true)]
public class InternalService
{
}

[VersionRoute]

版本化路由，格式：/api/{version}/[area]/[controller]/[action]

[VersionRoute("v1")]
public class OrderService
{
}

[SchemaId]

自定义 Swagger SchemaId，避免同名类冲突。

[SchemaId(Prefix = "Order", Suffix = "Input")]
public class OrderInput
{
}

8. 数据生成特性

[NotGen]

数据生成/同步时忽略该属性。

1 2	[NotGen] public DateTime SyncTime { get; set; }

[ScanCacheKeys]

标记缓存键常量类，供系统扫描注册。

[ScanCacheKeys]
public static class MyCacheKeys
{
    public const string MyData = "MyModule:Data";
}

[ScanTaskNames]

标记任务名称常量类，供系统扫描注册。

特性速查表

特性	分类	说明
`[Transaction]`	事务	声明式事务控制
`[AdminTransaction]`	事务	使用权限库的声明式事务
`[Login]`	权限	标记登录接口
`[ValidatePermission]`	权限	登录+权限验证
`[ApiAccess]`	权限	接口级访问控制
`[NoOperationLog]`	权限	禁用操作日志
`[Database]`	数据库	标记实体所属数据库
`[InjectSingleton]`	DI	单例生命周期
`[InjectScoped]`	DI	作用域生命周期
`[InjectTransient]`	DI	瞬态生命周期
`[NonRegisterIOC]`	DI	排除自动注册
`[Snowflake]`	ID生成	雪花算法ID
`[OrderGuid]`	ID生成	有序GUID
`[ServerTime]`	时间	自动服务器时间
`[ApiGroup]`	API	Swagger分组
`[VersionRoute]`	API	版本化路由
`[SchemaId]`	API	Swagger SchemaId
`[NotGen]`	数据生成	同步时忽略
`[ScanCacheKeys]`	数据生成	缓存键扫描
`[ScanTaskNames]`	数据生成	任务名称扫描

#中台 #中台/.NET模板 #中台/DI生命周期 #中台/特性注解