SZORM.Attribute 1.0.1

SZORM.Attribute - .NET ORM 属性定义库

SZORM.Attribute 是 SZORMCore ORM 框架的属性定义库，零依赖，用于定义实体类与数据库表之间的映射关系。

✨ 功能特性

• ✅ 零依赖 - 不引用任何其他包，轻量级
• ✅ 表映射 - 使用 [SZTable] 映射实体类到数据库表
• ✅ 列映射 - 使用 [SZColumn] 配置列属性（主键、非空、长度等）
• ✅ 索引支持 - 使用 [SZIndex] 定义数据库索引
• ✅ 加密支持 - 支持 SM4/AES 字段级加密
• ✅ .NET 6+ 兼容 - 支持 AOT 编译和裁剪

📁 项目结构

SZORM.Attribute/
├── SZORMAttribute.cs      # 核心属性定义（SZTable、SZColumn）
├── EncryptMode.cs          # 加密模式枚举（SM4、AES）
└── SZIndexAttribute.cs     # 索引属性定义

🚀 快速开始

1. 安装

dotnet add package SZORM.Attribute

或直接在 .csproj 中添加：

<ItemGroup>
  <PackageReference Include="SZORM.Attribute" Version="1.0.0" />
</ItemGroup>

2. 定义实体类

using SZORM.Attribute;
using System;

// 映射到 Users 表
[SZTable("Users")]
public class User
{
    // 主键
    [SZColumn(IsPrimaryKey = true)]
    public long Id { get; set; }

    // 非空，最大长度 50
    [SZColumn(IsNotNull = true, MaxLength = 50)]
    public string UserName { get; set; }

    // 唯一约束
    [SZColumn(IsUnique = true, MaxLength = 100)]
    public string Email { get; set; }

    // 最大长度，可为空
    [SZColumn(MaxLength = 200)]
    public string Address { get; set; }

    // 默认值
    [SZColumn(DefaultValue = "GETDATE()")]
    public DateTime CreateTime { get; set; }

    // 忽略此字段（不映射到数据库）
    [SZColumn(IsIgnore = true)]
    public string TempData { get; set; }

    // 加密存储（SM4）
    [SZColumn(IsEncrypt = true, EncryptMode = EncryptMode.SM4)]
    public string IdCard { get; set; }

    // 加密存储（AES）
    [SZColumn(IsEncrypt = true, EncryptMode = EncryptMode.AES)]
    public string BankCard { get; set; }
}

// 定义索引
[SZTable("Orders")]
[SZIndex("IX_Orders_UserId", nameof(Order.UserId))]
[SZIndex("IX_Orders_CreateTime", nameof(Order.CreateTime), IsUnique = false)]
public class Order
{
    [SZColumn(IsPrimaryKey = true)]
    public long Id { get; set; }

    [SZColumn(IsNotNull = true)]
    public long UserId { get; set; }

    [SZColumn(IsNotNull = true)]
    public decimal Amount { get; set; }

    [SZColumn(DefaultValue = "GETDATE()")]
    public DateTime CreateTime { get; set; }
}

📚 详细功能

1. SZTableAttribute - 表映射

// 指定表名
[SZTable("Users")]
public class User { }

// 使用默认约定（类名 = 表名）
[SZTable]  // 或省略属性
public class Users { }

2. SZColumnAttribute - 列映射

主键配置

public class User
{
    // 主键（自动生成 SnowID）
    [SZColumn(IsPrimaryKey = true)]
    public long Id { get; set; }
}

非空约束

public class User
{
    // 非空字段
    [SZColumn(IsNotNull = true, MaxLength = 50)]
    public string UserName { get; set; }
}

唯一约束

public class User
{
    // 唯一约束
    [SZColumn(IsUnique = true, MaxLength = 100)]
    public string Email { get; set; }
}

长度限制

public class User
{
    // 指定最大长度
    [SZColumn(MaxLength = 200)]
    public string Address { get; set; }

    // 注意：加密字段需要更长的列（加密后长度增加）
    [SZColumn(IsEncrypt = true, MaxLength = 64)]  // 建议 >= 64
    public string IdCard { get; set; }
}

默认值

public class User
{
    // 数据库默认值
    [SZColumn(DefaultValue = "GETDATE()")]
    public DateTime CreateTime { get; set; }

    // 或 .NET 默认值
    public bool IsActive { get; set; } = true;
}

忽略字段

public class User
{
    // 此字段不会映射到数据库列
    [SZColumn(IsIgnore = true)]
    public string TempData { get; set; }

    // 计算属性（不映射）
    [SZColumn(IsIgnore = true)]
    public string DisplayName => $"{FirstName} {LastName}";
}

3. 加密配置

SM4 加密

public class User
{
    // SM4 加密（国密算法）
    [SZColumn(IsEncrypt = true, EncryptMode = EncryptMode.SM4)]
    public string IdCard { get; set; }
}

AES 加密

public class User
{
    // AES-256-CBC 加密
    [SZColumn(IsEncrypt = true, EncryptMode = EncryptMode.AES)]
    public string BankCard { get; set; }
}

自定义加密转换器

// 1. 定义自定义转换器
public class MyEncryptConverter : IDbEncryptConverter
{
    public object Convert(object value)
    {
        // 自定义加密逻辑
        return Encrypt(value);
    }

    public object ConvertBack(object value)
    {
        // 自定义解密逻辑
        return Decrypt(value);
    }

    public object Encrypt(object value)
    {
        // 加密（写入数据库时使用）
        return Encrypt(value);
    }

    public object Decrypt(object value)
    {
        // 解密（从数据库读取时使用）
        return Decrypt(value);
    }
}

// 2. 在实体中指定转换器
public class User
{
    [SZColumn(IsEncrypt = true, EncryptConverterType = typeof(MyEncryptConverter))]
    public string SecretData { get; set; }
}

4. SZIndexAttribute - 索引定义

[SZTable("Users")]
[SZIndex("IX_Users_Email", nameof(User.Email), IsUnique = true)]  // 唯一索引
[SZIndex("IX_Users_CreateTime", nameof(User.CreateTime))]         // 普通索引
public class User
{
    [SZColumn(IsPrimaryKey = true)]
    public long Id { get; set; }

    [SZColumn(IsNotNull = true, MaxLength = 100)]
    public string Email { get; set; }

    public DateTime CreateTime { get; set; }
}

5. EncryptMode 枚举

public enum EncryptMode
{
    /// <summary>
    /// SM4 加密（国密算法，128位密钥）
    /// </summary>
    SM4 = 1,

    /// <summary>
    /// AES 加密（AES-256-CBC）
    /// </summary>
    AES = 2
}

🔗 与其他项目的关系

┌─────────────────────────────────────┐
│        你的应用程序                   │
│  (引用 SZORM.Attribute)            │
│  (定义实体类：User.cs, Order.cs)   │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│    SZORM.Attribute                  │
│  (零依赖，只定义 Attribute)         │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│    SZORM.Core                      │
│  (ORM 核心引擎，引用 Attribute)     │
│  (实现：DbContext, DbSet, SQL生成) │
└─────────────────────────────────────┘

设计优势：

• 实体类只需引用 SZORM.Attribute（零依赖）
• ORM 核心引擎 SZORM.Core 才需要引用完整的 ORM 功能
• 分层清晰，易于维护和扩展

📝 使用示例

完整示例：用户实体

using SZORM.Attribute;
using System;
using System.Collections.Generic;

namespace MyApp.Models
{
    [SZTable("Users")]
    [SZIndex("IX_Users_Email", nameof(User.Email), IsUnique = true)]
    [SZIndex("IX_Users_CreateTime", nameof(User.CreateTime))]
    public class User
    {
        [SZColumn(IsPrimaryKey = true)]
        public long Id { get; set; }

        [SZColumn(IsNotNull = true, MaxLength = 50)]
        public string UserName { get; set; }

        [SZColumn(IsNotNull = true, IsUnique = true, MaxLength = 100)]
        public string Email { get; set; }

        [SZColumn(IsNotNull = true, MaxLength = 64)]
        public string PasswordHash { get; set; }

        // 加密字段（SM4）
        [SZColumn(IsEncrypt = true, EncryptMode = EncryptMode.SM4, MaxLength = 64)]
        public string IdCard { get; set; }

        // 加密字段（AES）
        [SZColumn(IsEncrypt = true, EncryptMode = EncryptMode.AES, MaxLength = 128)]
        public string BankCard { get; set; }

        // 哈希索引（用于加密字段的查询）
        [SZColumn(MaxLength = 64)]
        public string IdCardHash { get; set; }

        [SZColumn(DefaultValue = "GETDATE()")]
        public DateTime CreateTime { get; set; }

        [SZColumn(DefaultValue = "1")]
        public int Status { get; set; }

        // 忽略字段（不映射到数据库）
        [SZColumn(IsIgnore = true)]
        public string ConfirmPassword { get; set; }
    }
}

完整示例：订单实体

namespace MyApp.Models
{
    [SZTable("Orders")]
    [SZIndex("IX_Orders_UserId", nameof(Order.UserId))]
    [SZIndex("IX_Orders_CreateTime", nameof(Order.CreateTime))]
    public class Order
    {
        [SZColumn(IsPrimaryKey = true)]
        public long Id { get; set; }

        [SZColumn(IsNotNull = true)]
        public long UserId { get; set; }

        [SZColumn(IsNotNull = true)]
        public decimal Amount { get; set; }

        [SZColumn(MaxLength = 500)]
        public string Description { get; set; }

        [SZColumn(DefaultValue = "'Pending'")]
        public string Status { get; set; }

        [SZColumn(DefaultValue = "GETDATE()")]
        public DateTime CreateTime { get; set; }
    }
}

⚙️ 配置说明

在项目中使用

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    
    <PackageReference Include="SZORM.Attribute" Version="1.0.0" />
  </ItemGroup>

</Project>

在 ORM 核心中使用

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    
    <ProjectReference Include="..\SZORM.Attribute\SZORM.Attribute.csproj" />
  </ItemGroup>

</Project>

🤔 常见问题

1. 为什么需要单独的属性定义库？

答：为了实现关注点分离和零依赖。

• 实体类项目只需要引用 SZORM.Attribute（非常小，零依赖）
• ORM 核心引擎 SZORM.Core 才需要引用完整的数据库驱动和 ORM 功能
• 这样实体类可以在多个项目中共享，而不需要引入不必要的依赖

2. 可以不使用 Attribute，使用约定吗？

答：当前版本主要使用 Attribute 进行配置，未来版本可能支持 Fluent API 配置。

3. 加密字段的长度应该如何设置？

答：

• SM4 加密：明文长度 + 16~32 字符（Padding）
• AES 加密：明文长度 + 16~32 字符（Padding）
• 建议：身份证 18 字符 → 加密后 Base64 约 32 字符 → 字段 MaxLength 建议 >= 48
• 最佳实践：加密字段的 MaxLength 设置为明文的 2 倍

4. 如何升级到新版本？

dotnet add package SZORM.Attribute --version 1.1.0

📄 许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📧 联系方式

如有问题或建议，请提交 Issue 或联系项目维护者。

⚡ 相关链接

• SZORMCore 主项目
• SZORMCore 文档
• 问题反馈