XiuXian.China.Nations 1.0.2

XiuXian.China.Nations 🇨🇳

基于国标（GB/T 2260）的 56 民族数据处理库 — 零依赖、线程安全、开箱即用。

开源地址

• Gitee：https://gitee.com/yzxs949/xiu-xian/tree/master/XiuXian.China.Nations
• NuGet：https://www.nuget.org/packages/XiuXian.China.Nations

功能特性

支持框架

• .NET Standard 2.0+（兼容 .NET Framework 4.6.1+ / .NET Core 2.0+ / .NET 5+ / .NET 6+ / .NET 8+ / .NET 10+）
• Mono / Xamarin / Unity

快速开始

安装

dotnet add package XiuXian.China.Nations

或者通过 NuGet 包管理器：

Install-Package XiuXian.China.Nations

一分钟上手

using XiuXian.China.Nations.Services;
using XiuXian.China.Nations.Enums;
using XiuXian.China.Nations.Extensions;

// 1. 获取所有民族
var all = NationLibrary.GetAll();
Console.WriteLine($"共 {all.Count} 个民族");

// 2. 按编码查询（支持 "1" 或 "01"）
var han = NationLibrary.GetByCode("01");      // 汉族
var menggu = NationLibrary.GetByCode("02");   // 蒙古族

// 3. 按名称查询
var hui = NationLibrary.GetByName("回族");

// 4. 按枚举查询
var zang = NationLibrary.GetByEnum(NationEnum.Zang);

// 5. 模糊搜索（名称/拼音/短码）
var search1 = NationLibrary.Search("蒙");      // 按名称
var search2 = NationLibrary.Search("Meng");    // 按拼音
var search3 = NationLibrary.Search("MGZ");     // 按短码

项目结构

XiuXian.China.Nations/
├── Enums/
│   └── NationEnum.cs          # 56个民族枚举定义
├── Models/
│   └── NationInfo.cs          # 民族信息实体模型
├── Services/
│   └── NationLibrary.cs       # 民族数据核心服务（静态类）
├── Extensions/
│   └── NationExtensions.cs    # 民族扩展方法
├── Utils/
│   └── CodeNormalizer.cs      # 国标编码标准化工具
├── XiuXian.China.Nations.csproj
└── README.md

使用指南

1. 数据查询

// 获取全部列表
IReadOnlyList<NationInfo> all = NationLibrary.GetAll();

// 精确查询（返回 null 表示未找到）
NationInfo? nation = NationLibrary.GetByCode("56");        // 编码
NationInfo? nation = NationLibrary.GetByName("基诺族");     // 名称
NationInfo? nation = NationLibrary.GetByEnum(NationEnum.JiNuo);  // 枚举

// 短码查询（可能返回多条）
IReadOnlyList<NationInfo> results = NationLibrary.GetByShortCode("HZ");

2. 枚举 ↔ 编码 双向转换

// 枚举 → 国标编码
string code = NationLibrary.GetCodeByEnum(NationEnum.Han);   // "01"

// 国标编码 → 枚举
NationEnum en = NationLibrary.GetEnumByCode("02");           // NationEnum.MengGu

3. 模糊搜索

支持按名称、拼音、短码三个维度同时模糊匹配，内部使用 ToUpperInvariant() 进行大小写不敏感比较：

// 按中文名称搜索
var r1 = NationLibrary.Search("蒙古");    // → [蒙古族]

// 按拼音搜索
var r2 = NationLibrary.Search("meng");    // → [蒙古族]

// 按短码搜索
var r3 = NationLibrary.Search("MGZ");     // → [蒙古族]

// 不传参数返回全部
var all = NationLibrary.Search(null);

4. 排序与校验

// 按拼音排序
var sorted = NationLibrary.OrderByPinyin();

// 校验编码/名称合法性
bool valid = NationLibrary.IsValidCode("01");    // true
bool valid = NationLibrary.IsValidName("汉族");   // true

5. 扩展方法

using XiuXian.China.Nations.Extensions;

var nation = NationLibrary.GetByCode("01");

bool isHan      = nation.IsHan();         // true — 判断汉族（null → false）
bool isMinority = nation.IsMinority();    // false — 判断少数民族（null/其他民族 → false）
string shortName = nation.GetShortName(); // "汉" — 简称（取首字/首两字）

// 批量查询
var batch = new[] { "01", "02", "03" }.GetNationsByCodes();
var batch = new[] { "汉族", "回族" }.GetNationsByNames();

扩展方法说明：

6. 短码歧义检测

// 检查某个短码是否有歧义
bool ambiguous = NationLibrary.IsAmbiguousShortCode("HZ"); // true（汉/回）

// 获取所有重复的短码
var duplicates = NationLibrary.GetDuplicateShortCodes();
// → { "HZ": [汉族, 回族], "ZZ": [藏族, 壮族], ... }

数据模型

NationInfo 实体

[Serializable]
public class NationInfo
{
    public string    Code       { get; set; }  // 国标编码 "01"~"56", "99"（默认 string.Empty）
    public string    Name       { get; set; }  // 中文名称（如"蒙古族"，默认 string.Empty）
    public string    Pinyin     { get; set; }  // 拼音标识（如"MengGu"，默认 string.Empty）
    public string    ShortCode  { get; set; }  // 短码（拼音首字母+Z，默认 string.Empty）
    public NationEnum EnumValue { get; set; }  // 枚举值
}

重写方法：

⚠️ GetHashCode() 基于可变属性 Code，放入 Dictionary/HashSet 后请勿修改 Code。

NationEnum 枚举

枚举名称使用驼峰拼音（如 MengGu、WeiWuEr、KeErKeZi）。

ShortCode 规则

取各字拼音首字母 + Z(族) 后缀：

已知短码重复

以下短码对应多个民族，GetByShortCode() 返回列表而非单条：

API 参考

NationLibrary（核心服务）

内部索引结构：

所有索引通过 Lazy<T> 实现线程安全的延迟初始化。

完整 API 列表：

NationExtensions（扩展方法）

CodeNormalizer（编码标准化工具）

位于 XiuXian.China.Nations.Utils 命名空间，被 NationLibrary 内部调用，也可单独使用。

NormalizeCode 规则：

• 空白/空输入 → 返回 string.Empty
• 1 位纯数字 → 左侧补零
• 2 位纯数字 → 直接返回
• 非纯数字输入 → 原样返回，由调用方处理

注意事项

• 查询安全：所有查询方法返回 null 或空列表，不会抛出异常
• 编码容错：支持 "1" 和 "01" 两种编码格式（通过 CodeNormalizer.NormalizeCode() 自动标准化）
• 短码歧义：HZ/ZZ/MZ/YZ/DZ/SZ 有重复，使用 GetByShortCode() 获取列表
• HashCode 不可变：NationInfo 重写了 Equals()/GetHashCode()（基于 Code 的 Ordinal 比较），放入 Dictionary/HashSet 后不要修改 Code
• 序列化：NationInfo 标记了 [Serializable]，适用于 JSON/数据库序列化
• IsMinority 边界："其他民族"（Code="99"）既不是汉族，也不计入少数民族

版本历史

关注我们

公众号：.NET修仙日记

定期分享 .NET 开发实战、开源项目解读与技术干货。

许可证

MIT License — 详见 LICENSE 文件。

XiuXian.China.Nations — 让民族数据处理更简单 🇨🇳

开源地址：https://gitee.com/yzxs949/xiu-xian/tree/master/XiuXian.China.Nations

公众号：.NET修仙日记