家谱电子化实战：JavaScript + C# 前后端协作与数据模型设计-育师

简介：本资源为基于JavaScript与C#的FamilyTree家谱电子化项目设计源码，面向需要完成家族族谱数字化管理系统的开发者与课程设计学习者，尤其适合具备一定前后端基础、希望参考完整工程结构的中高级人员。项目通过JavaScript负责前端交互与页面呈现，C#承担后端业务逻辑与数据处理，实现家族成员信息的录入、维护与可视化展示。压缩包共290个文件，约60.45MB，其中包含77个DLL、42个XML、28个JavaScript、25个Nupkg、24个XDT、21个CS文件，以及CSHTML、CSS、配置文件与构建脚本等，覆盖依赖库、配置、视图与编译产物，目录结构完整，便于按模块查阅。目前已有396人学习下载。读者可从中获取一套可直接运行或二次开发的家谱管理系统源码，理解前后端协作方式、项目分层组织与配置管理思路，并借助现有结构快速搭建自己的族谱应用。

1. 家谱电子化这件事，为什么我最后选了 JavaScript + C# 这套组合

前阵子帮一个宗亲会做族谱数字化，需求听起来简单：把纸质家谱录入、存起来、能查、能导出。真上手才发现坑不少——家族成员关系是典型的树形结构，但现实中存在过继、入赘、改嫁、同名同辈等一堆非标准情况，纯前端存 localStorage 根本扛不住，纯后端又没法让老一辈在手机上直接翻看。最后落地的方案是前端 JavaScript 负责交互和树形渲染，后端 C# 负责数据持久化和复杂查询，中间用 REST 接口打通。这套 FamilyTree 家谱电子化项目源码就是按这个思路组织的，包含前端页面、C# 服务端、CSS 样式和数据库脚本。它适合两类人：一是想拿现成架子改造成自己家族系统的开发者，二是正在学 JavaScript 与 C# 前后端协作、需要一个真实业务场景练手的同学。下面我按实际拆包的顺序，把结构、跑法、参数和踩过的坑一次讲清。

2. 拆开源码包：目录结构、技术栈与数据模型怎么对上号

2.1 目录分层与文件职责

拿到包先别急着 dotnet run，花十分钟把目录过一遍能省后面两小时。这个项目的典型分层是这样的：前端资源集中在wwwroot或独立的frontend目录，里面按js/、css/、pages/分开；C# 服务端通常是Controllers/、Models/、Services/、Data/四块；数据库脚本单独放sql/或Scripts/。我一般会先找入口文件——前端的index.html和后端的Program.cs（或Startup.cs），这两个决定了整个项目怎么启动、路由怎么配。

# 先看整体结构，重点确认前端资源目录和后端入口 tree -L 3 -I 'bin|obj|node_modules' # 输出示例（不同版本略有差异）： # . # ├── Controllers/ # C# 接口层 # ├── Models/ # 实体类，FamilyMember 等 # ├── Services/ # 业务逻辑，关系计算 # ├── Data/ # 数据库上下文 # ├── wwwroot/ # │ ├── js/ # 前端逻辑 # │ ├── css/ # 样式 # │ └── index.html # └── sql/ # 建表脚本

这段命令的作用是快速建立空间感。-L 3限制三层避免输出爆炸，-I排除编译产物。重点看Models/里有没有FamilyMember、Relation这类实体，它们决定了家谱数据能表达多复杂的关系。如果只有一张平表，那过继、入赘这些场景就得自己扩展。

2.2 家谱数据模型：为什么不能只用一张表

家谱的核心是「人」和「关系」。新手最容易犯的错是设计成id, name, father_id, mother_id一张表完事，结果遇到配偶、兄弟姐妹、辈分排序就抓瞎。这个项目里我看到的常见做法是拆成两张表：FamilyMember存个人属性，Relation存两人之间的边。

表名	关键字段	作用
FamilyMember	Id, Name, Gender, BirthDate, Generation, Remark	存个人基本信息，Generation 表示第几世
Relation	Id, FromId, ToId, RelationType	存关系边，RelationType 区分父子/配偶/过继
Family	Id, Surname, Origin, CreatedAt	存家族元信息，支持多家族

Generation这个字段很关键，它让「按辈分排序」和「同辈校验」变得简单。RelationType用枚举而不是字符串，查询时性能更好，也避免「父亲」「父」这种脏数据。如果你要扩展，建议再加一个RelationMeta字段存 JSON，把「过继给谁」「入赘时间」这类非标准信息塞进去，比无限加列优雅。

2.3 前后端接口约定

JavaScript 和 C# 之间靠 HTTP 接口通信，约定不清就会出现前端传fatherId、后端等parentId的翻车。这个项目里接口一般集中在Controllers/FamilyController.cs，前端在js/api.js里封装调用。我习惯先看接口返回结构再写前端。

// js/api.js 里常见的封装方式 async function getMemberTree(familyId) { // 统一走 /api/family/tree，参数用 query string const res = await fetch(`/api/family/tree?familyId=${familyId}`, { method: 'GET', headers: { 'Content-Type': 'application/json' } }); if (!res.ok) throw new Error(`请求失败: ${res.status}`); return res.json(); // 期望返回嵌套的树形结构 }

逻辑说明：fetch用 GET 拿树形数据，familyId作为查询参数区分不同家族。参数说明：familyId必传，缺失时后端应返回 400 而不是空树，否则前端会误以为家族没人。返回结构建议是{ code, data, message }三段式，data里放嵌套节点，前端递归渲染时不用再拼装。如果后端直接返回扁平数组，前端就得自己建索引再组树，多一步但更灵活，看你团队习惯。

3. 把项目跑起来：环境、数据库与前后端联调步骤

3.1 环境准备与依赖安装

跑这个项目需要 .NET SDK（建议 6.0 及以上）和任意现代浏览器，前端如果用了构建工具还需要 Node.js。我一般先确认版本，避免「在我机器上能跑」的玄学。

# 检查 .NET 版本，低于 6.0 建议升级 dotnet --version # 还原后端依赖 dotnet restore # 如果有前端构建步骤 npm install npm run build

dotnet restore会根据.csproj拉取 NuGet 包，常见依赖是 EntityFrameworkCore 和对应的数据库驱动。如果卡在还原，先看网络和 NuGet 源配置，别急着删obj。npm install只在有package.json时需要，纯静态前端可以跳过。

3.2 数据库初始化

家谱数据必须落库，SQLite 适合单机演示，SQL Server 或 MySQL 适合多人访问。项目里通常有建表脚本，先执行再改连接串。

-- sql/init.sql 核心建表语句 CREATE TABLE FamilyMember ( Id INTEGER PRIMARY KEY AUTOINCREMENT, Name NVARCHAR(50) NOT NULL, Gender TINYINT NOT NULL, -- 0 未知 1 男 2 女 Generation INT NOT NULL, -- 第几世 BirthDate DATE, Remark NVARCHAR(200) ); CREATE TABLE Relation ( Id INTEGER PRIMARY KEY AUTOINCREMENT, FromId INT NOT NULL, ToId INT NOT NULL, RelationType TINYINT NOT NULL, -- 1 父子 2 配偶 3 过继 FOREIGN KEY (FromId) REFERENCES FamilyMember(Id), FOREIGN KEY (ToId) REFERENCES FamilyMember(Id) );

逻辑说明：FamilyMember存人，Relation存边，外键保证不会出现指向不存在成员的脏关系。参数说明：Gender和RelationType用 TINYINT 省空间，但要在代码里定义枚举对应，别裸写数字。Generation建索引后按辈分查询会快很多。执行完脚本记得在appsettings.json里改连接串，SQLite 是文件路径，SQL Server 是完整连接字符串。

3.3 启动与联调

后端和前端分别启动，或者后端托管静态文件一起跑。联调时重点看浏览器 Network 面板和后端控制台。

# 启动后端，默认监听 5000 或 5001 dotnet run # 如果前端独立启动 npm run dev

启动后先访问健康检查接口（如果有/api/health），再打开首页。常见现象是页面能开但树是空的，这时按 F12 看/api/family/tree返回什么。如果是 401，检查有没有鉴权中间件；如果是 500，看后端日志里的异常堆栈，多半是连接串或表结构不匹配。联调通过后，试着新增一个成员再刷新，确认写入和读取都正常，这一步过了基本就稳了。

4. 避坑与排查：家谱项目里最容易翻车的五件事

4.1 递归查树导致栈溢出

现象：家族人数上千后，查询接口变慢甚至进程崩溃。原因：用递归函数逐层查数据库，N+1 查询加上深递归。解决：一次性把FamilyMember和Relation全查出来，在内存里组树，或者用 CTE 递归查询交给数据库。我一般选前者，数据量在万级以内内存完全扛得住。

4.2 中文姓名排序错乱

现象：按姓名排序时「张」跑到「李」前面。原因：数据库默认排序规则是二进制或英文规则，不认拼音。解决：建表时指定COLLATE Chinese_PRC_CI_AS（SQL Server）或在应用层用localeCompare排序。前端排序更灵活，但大数据量时还是数据库排更省事。

4.3 关系环导致无限循环

现象：渲染树时页面卡死。原因：数据录入错误形成 A 是 B 的父亲、B 又是 A 的父亲的环。解决：写入Relation前做环检测，用并查集或简单的 DFS 判断ToId是否已能到达FromId。这个校验放在 C# 服务层，前端也加一层提示，双保险。

4.4 日期格式前后端不一致

现象：生日显示成Invalid Date或差一天。原因：C# 的DateTime序列化成 ISO 格式带时区，JavaScriptnew Date()解析时区处理不一致。解决：后端统一返回yyyy-MM-dd字符串，前端按字符串处理，需要计算年龄时再手动解析，别直接丢给Date构造函数。

4.5 并发写入覆盖

现象：两个人同时录入，后提交的覆盖了先提交的。原因：没做乐观锁，更新时直接覆盖整行。解决：FamilyMember加RowVersion字段，C# 用[Timestamp]特性，更新时带上版本号，冲突就提示重试。家谱录入场景并发不高，但宗亲会多人同时操作时这个坑很真实。

5. 进阶技巧：用 Generation 字段做辈分校验与导出优化

5.1 辈分自动校验

录入时最容易出错的是辈分填错，导致树形结构错乱。利用Generation字段可以在保存前做校验：如果新增成员指定了父亲，那他的Generation必须等于父亲的Generation + 1。

// Services/FamilyService.cs 里的校验逻辑 public bool ValidateGeneration(FamilyMember member, FamilyMember father) { // 父亲存在时，辈分必须严格加一 if (father != null && member.Generation != father.Generation + 1) { return false; } // 配偶辈分必须相同 // ... 其他校验 return true; }

逻辑说明：这个方法在保存前调用，father为 null 表示是始祖，不校验。参数说明：member.Generation来自前端表单，father.Generation从数据库查。返回 false 时接口应返回具体错误信息，别只给「保存失败」。这个校验能拦住八成以上的录入错误，比事后修树省事得多。

5.2 导出 PDF 的字体坑

家谱最终要导出成 PDF 给长辈看，中文乱码是高频问题。常见做法是用iTextSharp或PuppeteerSharp，关键是嵌入中文字体。

// 用 iTextSharp 导出时嵌入字体 var fontPath = Path.Combine(env.WebRootPath, "fonts", "simsun.ttf"); var baseFont = BaseFont.CreateFont(fontPath, BaseFont.IDENTITY_H, BaseFont.EMBEDDED); var font = new Font(baseFont, 12);

逻辑说明：IDENTITY_H表示用 Unicode 编码，EMBEDDED把字体嵌进 PDF，换台机器也不会乱码。参数说明：字体文件要放对路径，simsun.ttf注意版权，商用换开源字体如思源宋体。导出前先小批量测试，确认分页和缩进正常再全量跑。