自定义特性

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

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

事务特性

[Transaction]

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

[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 才能生效。

权限与访问特性

[Login]

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

[Login]
public async Task<IResultOutput<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 Task<IResultOutput> Ping() { }

数据库特性

[Database]

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

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

[AdminTransaction]

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

DI 生命周期特性

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

[InjectSingleton]
public class MyCacheService { }

[InjectScoped]
public class MyService { }

[InjectTransient]
public class MyTool { }

[NonRegisterIOC]

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

[NonRegisterIOC]
public class MyCustomService { }

Id 生成特性

[Snowflake]

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

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

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

[OrderGuid]

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

适用场景

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

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

时间特性

[ServerTime]

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

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

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

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 { }

数据生成特性

[NotGen]

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

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

[ScanCacheKeys]

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

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

[ScanTaskNames]

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