FreeSql Usage Framework · Claude Code Skill

基于 128 篇 FreeSql 官方文档（6.7MB）深度调研提炼的使用规范与最佳实践框架。

安装

npx claude-skill-freesql

或者：

npx install-freesql-skill

全局安装（postinstall 自动执行）：

npm install -g claude-skill-freesql

这是什么？

这是一个 Claude Code Skill，当你在 Claude Code 中编写或审查 FreeSql 代码时，它会自动激活并提供：

• 6 个核心心智模型：IFreeSql 单例、双模式并存、UnitOfWork 事务边界、导航属性、全局过滤器+AOP、BulkCopy
• 10 条决策启发式：覆盖 Web 项目、多租户、分库分表、乐观锁等场景
• 10 条反模式：明确列出错误做法和正确做法
• 完整的问题分类与研究流程：确保回答基于真实文档而非编造

激活方式

安装后，在 Claude Code 中以下方式均可激活：

• 输入 /freesql-usage-framework
• 直接提问 FreeSql 相关问题（自动激活）
• 说「帮我看看这段 FreeSql 代码」「FreeSql 报错了」「FreeSql 和 EF Core 怎么选」

核心内容

心智模型

| # | 模型 | 一句话 | |---|------|--------| | 1 | IFreeSql 单例是第一性原理 | IFreeSql 必须单例，DbContext/Repository 多线程不安全 | | 2 | 双模式并存 | IFreeSql 细粒度操作 + DbContext EF Core 风格 | | 3 | UnitOfWork 事务边界是核心 | uow 范围内必须使用 uow.Orm 而非 fsql | | 4 | 导航属性是多表查询的核心 | 正确配置 Navigate 后，查询/级联/贪婪加载都简单 | | 5 | 全局过滤器 + AOP | GlobalFilter + Aop.AuditValue 实现横切关注点 | | 6 | BulkCopy 是大数据操作的唯一选择 | 万级以上必须用 BulkCopy（10x+ 提升） |

决策启发式

1. Web/API 项目 → IFreeSql + AddSingleton
2. 细粒度操作 + EF Core 风格 → IFreeSql + DbContext 并存
3. 跨方法事务 → UnitOfWorkManager + TransactionalAttribute
4. 多租户 → GlobalFilter + AsyncLocal
5. 万级以上批量插入 → BulkCopy
6. 导航属性多表查询 → Include / IncludeMany
7. 动态条件过滤 → WhereDynamicFilter
8. 分表场景 → AsTable
9. 跨数据库/分库 → FreeSql.Cloud
10. 乐观锁并发控制 → [Column(IsVersion = true)]

反模式清单

| # | 反模式 | 正确做法 | |---|--------|---------| | 1 | 生产环境使用 UseAutoSyncStructure | 只在开发环境使用 | | 2 | IFreeSql 不是单例 | AddSingleton | | 3 | UnitOfWork 范围内使用 fsql | 使用 uow.Orm | | 4 | Repository/DbContext 多线程使用 | 每个线程创建独立实例 | | 5 | Update/Delete 没有 Where 条件 | 显式 .Where(a => true) | | 6 | Navigate 设置表字段名 | 用类属性名 | | 7 | Repository 更新时 Column 设置 ServerTime | 去掉 ServerTime | | 8 | 分表实体使用延时加载 | 禁用延时加载 | | 9 | 乐观锁用于非 SetSource 更新 | 使用 SetSource | | 10 | 外部事务桥接后直接 Commit | tran.Commit() 提交 |

目录结构

freesql-usage-framework/
├── SKILL.md                          # 核心 Skill 文件
├── install.js                        # npx 安装脚本
├── package.json                      # npm 包配置
├── README.md                         # 本文档
├── LICENSE                           # MIT 许可证
├── scripts/                          # 工具脚本
└── references/
    └── research/                     # 调研结果
        ├── 01-architecture-lifecycle.md
        ├── 02-crud-query.md
        ├── 03-entity-mapping.md
        ├── 04-advanced-features.md
        ├── 05-providers-performance.md
        └── 06-ecosystem-antipatterns.md

调研来源

基于 FreeSql.Wiki.VuePress 官方文档（128 篇，6.7MB），涵盖：

• 入门文档、核心架构、生命周期
• CRUD 操作、查询 API、表达式函数
• 实体配置、CodeFirst、DbFirst、导航属性
• 事务管理、多租户、读写分离、分库分表
• AOP 事件、全局过滤器、性能优化
• 20+ 数据库提供者文档

相关项目

• FreeSql - FreeSql ORM 源码
• FreeSql.Wiki - FreeSql 官方文档
• claude-skill-sqlsugar - SqlSugar 使用规范 Skill（姊妹项目）

许可证

MIT