SqlEntity 6.0.12

SqlEntity

简洁的 SQL 映射与执行辅助库 (总览与目录模板段)。

简介

SqlEntity 提供对象化的字段/表结构与简化的查询/执行 API, 支持 SqlServer2008r2 及以上版本的数据库。

充分利用了IDE的智能提示与编译期检查, 让开发者可以更专注于业务逻辑的实现, 而不是SQL语句的拼接与调试。

可在此基础上实现Sql封装、数据库结构检查。已经研发了数据库升级工具，实现了开发上的闭环，解决数据库升级的痛点。

安装

dotnet add package SqlEntity

快速示例

var dao = new DAO(Helper.GetSettingBySqlServer());
if (dao.Open("数据库连接参数") == "1")
{
	var list = dao.From<UserSchema>()
		.Where(u => u.Age > 18 && u.Status == 1)
		.Order(u => u.CreateTime.Desc())
		.Select(u => new { u.Id, u.Name, u.Age })
		.Run<UserRow>()
		.WhenNull(err => { /** 错误处理 **/ });
}

目录 (自动合并后更多章节会出现在下方)

• 总览 / 分节使用指南
• 核心 DAO
• 字段与表达式
• 查询 DSL
• Schema 同步
• 工具与性能
• FAQ / 历史 / 变更

---

(以下内容由打包前脚本自动追加)

分节文档使用指南

1. 目的

帮助新开发者快速定位框架不同层面的功能说明, 缩短熟悉时间。

2. 快速开始

1. 阅读 api.md 获取总览
2. 根据任务需求跳转:
   • 数据库连接与执行 → 01-core-dao.md
   • 列与表达式构建 → 02-fields.md
   • 查询 DSL → 04-daofrom.md
   • Schema 维护 → 07-schema-sync.md
3. 实际编码时对照相应分节的示例与注意事项。

3. 搜索与导航

• 通过 IDE 全局搜索类名定位源码实现再回到文档比对。
• 每个分节文件底部附带返回链接 [返回目录](./api.md)。

4. 更新步骤

1. 修改/新增功能 → 更新对应分节文件
2. 若新增文件 → 修改 15-index.md
3. 在文件底部历史区块追加时间与说明

5. 约定

• 成功返回统一: "1" 或 Result<T>.ErrText == ""
• 失败返回: 错误文本 (不抛异常) 除非构造级严重错误
• 所有示例避免直接拼接不安全用户输入

6. 常见阅读路径示例

需求	推荐路径
写一个多表查询	02-fields → 04-daofrom
增加一个外键	03-accessors-root → 07-schema-sync
调优慢查询	13-performance → 04-daofrom
设计编号方案	10-coding-ids

7. FAQ 定位

• 执行报错: 01-core-dao.md 错误处理
• 列赋值异常: 02-fields.md Null/赋值章节
• 结构不匹配: 07-schema-sync.md 差异说明

---

返回总览

SqlEntity API 总览

说明: 本文件列出库中最重要的类别与核心类,作为后续详细说明的目录索引。可与 readme.md及分节文件交叉跳转。 使用约定:这里只介绍用途与定位,具体成员/方法由对应分节文件详述。

##目录

1. 核心基础对象

• DAO详解
• Result结构
• 变量与值容器

2. 字段与数据类型 Field 系列

• FieldInt 示例与操作
• 字段类型总览表
• 计算列 By / Case 示例

3. 访问器与实体 Table / Row / Root

• TableSchema详解
• TableAccessorBase详解
• RowEntity 用法
• RootBase详解

4. DaoFrom 链式查询详解
5. Sql组成类 (查询/写入/合成)
6. SqlWhere 与运算符语法
7. Schema 检测与结构同步

• Schema 差异类型说明

8. 参数/约束 Attribute (AccessorArgs)

• Attribute 验证流程顺序

9. 通用辅助类型 (Result / Conversion / Strings)
10. 编码与编号生成 (Coding* 系列)
11. 扩展应用层 (Report / Set / Power / Function)
12. 条码与杂项工具
13. 性能/集合支持

• 性能与事务最佳实践

14. 待补充章节
15. 快速类名索引
16. 待补充章节详细内容
17. 分节索引文件说明
18. 支持性文档
19. 更新历史

---

<a id="section-core"></a>

核心基础对象

详解文件: readmelist/01-core-dao.md

<a id="dao-detail"></a>

DAO详解

文件: DaoAndOther/DAO.cs 职责: 数据库连接与基础执行入口。封装 Open / Run / Select / SelectM / From 等操作, 管理连接参数与执行错误。 关联:

• DAOSetting / DaoConnectionArgs
• 部分类: DAO_Select, DAO_Execute, DAO_Find, DAO_New 分组概览:连接管理 / 执行与事务 / 查询 / 查找与统计 / DML包装 / 链式查询构建 / 编号生成 /语句工厂 /结构维护 /服务器信息。

<a id="result-structure"></a>

Result结构

详见 01-core-dao.md 与 09-common-utils.md。

• Result<T> / ResultList<T> 标准返回模型。

<a id="value-containers"></a> ###变量与值容器 详见 01-core-dao.md / 09-common-utils.md。

• CodingVar* / CVar* / ValueContainer<T> 用途说明。

---

<a id="fields-series"></a>

字段与数据类型 Field 系列

详解文件: readmelist/02-fields.md 接口: IField, IField2, IFieldSql, IFieldCode 职责: 映射列元数据 +生成 SQL片段。

<a id="fieldint-operations"></a>

FieldInt 示例与操作

文件: Field/FieldInt.cs (详细见 02-fields.md).

<a id="field-types-table"></a>

字段类型总览表

(表格保持不变)

<a id="calc-by-case"></a> ###计算列 By / Case 示例 示例保持原描述, 完整示例见 02-fields.md 与 05-sql-objects.md。

---

<a id="accessors-root"></a> ##访问器与实体 Table / Row / Root 详解文件: readmelist/03-accessors-root.md

<a id="tableschema-detail"></a>

TableSchema详解

(概述保持,细节见分节文件)

<a id="tableaccessorbase-detail"></a>

TableAccessorBase详解

(概述保持,细节见分节文件)

<a id="rowentity-usage"></a>

RowEntity 用法

(概述保持,细节见分节文件)

<a id="rootbase-detail"></a>

RootBase详解

(概述保持,细节见分节文件)

---

<a id="daofrom-detail"></a>

DaoFrom 链式查询详解

详解文件: readmelist/04-daofrom.md

---

<a id="sql-objects"></a>

Sql组成类 (查询/写入/合成)

详解文件: readmelist/05-sql-objects.md

---

<a id="sqlwhere-operators"></a>

SqlWhere 与运算符语法

详解文件: readmelist/06-sqlwhere-operators.md

---

<a id="schema-sync"></a>

Schema 检测与结构同步

详解文件: readmelist/07-schema-sync.md

<a id="schema-diff-types"></a>

Schema 差异类型说明

(概要保持,细节见分节文件)

---

<a id="attributes-accessorargs"></a>

参数/约束 Attribute (AccessorArgs)

详解文件: readmelist/08-attributes.md

<a id="attribute-validation-flow"></a>

Attribute 验证流程顺序

(概要保持,细节见分节文件)

---

<a id="common-utils"></a>

通用辅助类型 (Result / Conversion / Strings)

详解文件: readmelist/09-common-utils.md

---

<a id="coding-ids"></a>

编码与编号生成 (Coding* 系列)

详解文件: readmelist/10-coding-ids.md

---

<a id="application-layer"></a>

扩展应用层 (Report / Set / Power / Function)

详解文件: readmelist/11-application-layer.md

---

<a id="barcode-utils"></a>

条码与杂项工具

详解文件: readmelist/12-barcodes-utils.md

---

<a id="performance-support"></a>

性能/集合支持

详解文件: readmelist/13-performance.md

<a id="performance-best-practices"></a>

性能与事务最佳实践

(概要保持,细节见分节文件)

---

<a id="future-topics"></a>

待补充章节

(占位列表保持)

---

<a id="class-index"></a>

快速类名索引 (可扩展)

(保持原列表)

---

<a id="future-topics-detail"></a>

待补充章节详细内容

详解文件: readmelist/14-future-topics.md

---

<a id="section-index-files"></a>

分节索引文件说明

• 索引: readmelist/15-index.md
• README 衔接: readmelist/16-readme-link.md
• 使用指南: readmelist/README-sections.md -变更日志: readmelist/CHANGELOG-docs.md
• 文档历史: readmelist/HISTORY.md

---

<a id="supporting-docs"></a>

支持性文档

为提高可维护性新增辅助文件:

• 15-index.md统一索引导航
• README-sections.md 新人引导
• 16-readme-link.md 主 README 集成指引
• CHANGELOG-docs.md 文档更新日志
• HISTORY.md 历史阶段与规划记录

---

<a id="change-history"></a>

更新历史

2024-12-16 初稿建立 (重要类结构总览) 2024-12-17 扩展: DAO / TableSchema / TableAccessorBase / RowEntity / RootBase / FieldInt 2024-12-17 第二次扩展: DaoFrom / 运算符 / 字段总览 /计算列 / Attribute 流程 / Schema 差异 / 性能建议 2024-12-17 补充待补充章节详细内容 2024-12-17 增补锚点与分节文件链接, 修正标题格式 2024-12-17统一标题空格与支持性文档说明 2025-11-09纠正时间戳并标记当前日期为最新维护时间 2025-11-10 增补标准 <a id> 锚点以兼容 VS2022 与 GitHub

核心基础对象详解

本节深入说明 SqlEntity 的核心运行单元: DAO / Result / 值与变量容器。

1. DAO 深度说明

DAO 负责连接管理 + SQL执行 + 查询装配 + 编号生成 + 结构检测辅助。其实现按功能拆分为多个 partial 文件:

• DAO.cs 连接与基本入口
• DAO_Select.cs 查询与 Reader 映射
• DAO_Execute.cs 执行与事务封装
• DAO_Find.cs 单值/行获取
• DAO_New.cs 编号与新语句工厂

1.1 连接管理

构造: new DAO(DAOSetting setting, int connectTimeout=30, int commandTimeout=30) 关键成员:

• Open(string connString) 验证连接参数正确性 (立即 Open + Close 测试)
• Open(server,database,user,password) 拼接标准 SQL Server 字符串
• Open(DaoConnectionArgsItem) 通过配置对象
• OpenLocal(serverAlias,database) 针对数据库在本机使用Windows集成登录的场景
• OpenFile(path) 附加 MDF 文件 (LocalDB)
• 静态: OpenConnect(setting, connString) 返回一个可直接使用并保持打开的 DbConnection 错误返回统一为字符串 (成功为 "1") 或 Result<T>.ErrText。
• DAOSetting用于支持多数据库，当前仅实现 SQL Server，固定使用 Helper.GetSettingBySqlServer()

1.2 执行与事务

三层模式:

1. 非事务快速执行: ExecuteNoTrans(sql)
2. ADO.Net 事务: Execute(sql) / Execute(IEnumerable<string>)
3. TRY/CATCH 包装事务: ExecuteEx(sql) 自动生成异常再抛出脚本 补充:

• Run(sql) 创建 DaoRunner (聚合多条语句一次执行)
• Runs(sqls) 创建 DaoRunners (同事务逐条执行)
• Execute(SqlContent) 创建 DaoRunner 支持变量声明/错误聚合

1.3 查询体系

单表/多表/链式统一抽象:

• 表格返回: Select(string|SqlSelect|SqlSelectByJoin) → Result<DataTable>
• 多结果集: SelectM(string|SqlSelect[]) → Result<DataSet>
• Reader 映射: SelectToObj(sql, list) / SelectToObj(sql, Action<DaoDataReader>)
• 链式批量: 通过多个 DaoSelectorItem 聚合 → DaoSelector.Execute()
• 事务查询: SelectTrans / SelectMTrans

1.4 单值与统计

• 行数: GetCount(tableName, where) → Result<int>
• 是否存在: ValueExist(table, where) → "1" / "0"
• 列存在 / 表存在 / 过程存在: ColumnExist, TableNameExist, ProcedureExist
• 单值读取: FindValue(FieldX, where?) 返回强类型 Result<T>

1.5 编号与序列

• 生成13位单据号: NewBillId (头 + yyyyMMdd + 序号)
• 复合 ID: NewId14, NewId12, NewId10 不同长度与日期编码规则
• 普通递增: NewId (前缀 + 固定长度递增数字)
• 数值列递增: NewNumber / NewNumberLong
• 生成空闲编号: NullId 自左向右扫描空闲编号 (最多 99999)

1.6 新语句工厂

快速创建语法对象:

• NewSelect() / NewInsert() / NewUpdate(bool noWhere=false) / NewDelete()
• 复合: NewInsertOrUpdate(TableInner, where) / NewInsertByList(table) / NewInsertBySelect(table)

1.7 结构维护与备份

• DataBaseBack(path) 物理备份 (SQL Server)
• RemoveTable, RemoveColumn, RemoveDataBase 删除对象 (需谨慎)
• GetServerTime() 获取服务器当前时间 Result<DateTime>

1.8 错误处理模式

统一不抛异常 (除严重构造错误) → 返回 "错误文本" 或 Result.ErrText。调用端通过:

var r = dao.Select("select 1");
if(r.Item == null) Log(r.ErrText);

对批量执行: SqlContent.ErrList 聚合每个语句错误。

2. Result / ResultList 模型

2.1 结构

class Result<T> { T? Item; string ErrText; }
class ResultList<T> { List<T>? Item; string ErrText; }

2.2 语义

• 成功: ErrText == "" 且 Item 有值 (允许业务空值: Item == null)
• 失败: ErrText.Length > 0

2.3 常用链式辅助

• ToOK(value) / ToError(msg)
• WhenNull(action) / WhenErr(action) 用于集中处理

3. 值与变量容器

3.1 CodingVar

封装 SQL 变量声明/赋值/替换流程。 使用: SqlHelper.VarsDeclare(vars) + 后续语句中引用 @VarName。

3.2 CVar* 系列

包装变量类型并提供 .Name 引用，如 CVarNumeric, CVarText。

3.3 ValueContainer<T>

用于 Find(out ValueContainer<T> obj, ...) 形式从回调中携带结果。

4. 使用建议速览

• 所有数据库交互优先使用 Result<T> 防止异常层层冒泡。
• 大批事务构建 SqlContent 聚合后一次执行。
• 查询大量行优先 SelectToObj(回调) → 减少中间 DataTable 分配。
• 编号生成前可加业务前缀：NewId(table, col, 6, prefix)。
• DAO 对象比较底层，建议使用表访问器/链式查询/建立逻辑树等更高层封装。

5. 常见问题排查

问题	原因	对策
Open 返回错误文本	连接字符串错误 / 未设置 InitDbConnection	检查 DAOSetting 初始化
Select 返回空表	条件不符 / 字段名拼写	打印最终 SQL 确认列与条件
Update 不生效	SqlUpdate 无赋值项或 where 错误	确认 Add() 是否被调用
InsertOrUpdate 始终 Insert	where 条件不唯一或不匹配	检查条件列值是否存在
NullId 很慢	目标空间太大	缩短编号长度或改用顺序号

6. 事务策略建议

• 微操作(单条)使用 ExecuteNoTrans
• 多条强一致使用 Execute(IEnumerable<string>)
• 复杂脚本 + 容错使用 ExecuteEx
• 大批语句分块: 分批 Runs + 进度回调

---

返回目录

字段与数据类型详解

本节介绍各 Field 类型的构造模式、运算符重载、表达式与 Null 处理策略。

1. 架构接口层

• IField 基础列接口: 暴露 FieldName, Table, GetCaption(), 测试 Schema 兼容。
• IField2 额外支持动态设置列名 (反射自动补全)。
• IFieldSql 表达式列抽象 (结果不一定是物理列)。
• IFieldCode 支持编码/赋值时的代码生成辅助。

2. 标准列类型总览

类型	用途	构造示例	特别说明
FieldInt	整数/自增/主键	public FieldInt("标题")	通过 SetAutoNumberColumn 标记自增
FieldReal	精确/浮点数	new FieldReal(m,n,"标题")	小数的唯一推荐采用类型
FieldMoney	金额	new FieldMoney()	遗留类型，不建议使用，请用FieldReal
FieldBool	布尔标记	new FieldBool()	空值 → 默认 null
FieldDate	日期/时间	new FieldDate()	支持多种日期时间类型
FieldText	Unicode 文本	new FieldText(len)	长度 -1 表示 max
FieldChars	非 Unicode 文本	new FieldChars(len)	编码按 Collation
FieldGuid	唯一标识	new FieldGuid()	需在应用层生成 Guid
FieldBytes	二进制	new FieldBytes()	大对象慎用 SELECT *

3. 构造模式

1. 极简(推荐): 在 TableSchema 中直接写字段成员 public FieldInt Id = new FieldInt();
   • 由 RefreshFields() 自动注册列名与表。
2. 传入表: new FieldInt(this, "Id") 显式列名 → 适合自定义别名或特殊初始化。
3. 表达式列: 通过 TableSchema.By 创建 (不参与 Schema)。
4. 所有数据库表物理列的Field实例都应该在 TableSchema 中声明并创建。
5. 每个列对象都有名称、类型、标题、是否稀疏、以及一些相关参数（比如长度，小数位数等等），构建它们是为了完整还原数据库表的结构，供 DAO 进行 SQL 生成和数据映射。

4. 运算符与表达式

4.1 比较运算

• 数值: a > b, a >= 10, a == 变量, a != （SqlSelect)
• 文本 Like: name.LikeAll("abc") / LikeStart("abc") / LikeEnd("abc")
• Null: field == DBNull.Value / field != DBNull.Value

4.2 逻辑组合

• Where 表达式通过 & (AND) 与 | (OR) 组合: (price >=1 & store >0) | name.LikeAll("水")。

4.3 Select 投影

• field / "Alias" → SqlList 项
• field.ToSqlList("Alias")

4.4 赋值表达式

• .Let(value) → 生成 SqlEqualOrLet
• 与变量: .Let(codingVar) / .Let(FieldSqlInt)

4.5 递增/计算

• field.GetAppendSql(5) → 新表达式列 (field + 5)

5. Null 与类型转换

读取行值:

int value = field.GetValue(row, 0);
int? optional = field.GetData(row);
long l = field + reader; // 运算符重载

策略:

• 所有 GetValue 系列允许指定 Null 替代默认。
• 业务层应避免在真实空表示与 0 / 空串混淆。

6. 稀疏列 Sparse

• 通过 SetIsSparse() 标记列 → DDL 生成 ... SPARSE NULL 适用: 大量 Null 且行数很大 (节省存储)。
• 生成数据库构建语句时会使用它。

7. 主键与索引

在 TableSchema 中:

SetPrimaryKey(Id);
AddUniqueIndex(Code);
AddNotUniqueIndex(Name, Created);
SetAutoNumberColumn(IdInt);

• 注意: 更改主键需手动迁移数据。
• 生成数据库构建语句时会使用它们。

8. 表达式列与 Case

var total = By.RealFrom(Price * Store);
var level = By.Case(Store >=100 ,"A")
 .Case(Store >=50, "B")
 .Case(DBNull.Value, "C")
 .EndCase();

• 仅查询阶段使用，不参与更新/插入。
• By是 TableSchema 的属性。

9. Schema 检测匹配逻辑

IField.TestFieldSub(SchemaColumnsItem schemaCol) 检查:

• 类型名称一致
• 是否自增一致
• 主键列不允许 AllowNull
• 稀疏标记一致
• 这是构建 Schema 差异报告的基础。

10. 常见问题

问题	原因	方案
列名为空	未在极简构造后自动刷新	确保在 TableSchema 之内声明列对象，并且在 RootBase 之内声明表对象
表达式列更新失败	只读表达式	不要对表达式列执行 Update

---

返回目录

访问器与实体: TableAccessor / RowEntity / RootBase

1. TableSchema 回顾

见字段章节: 负责列集合与主键/索引/外键注册。是访问器的结构基石。

• 索引定义: AddIndex(isUnique, field1, field2...)
• 聚集索引定义: SetMainIndex(field1, field2...)
• 唯一索引定义: AddUniqueIndex(field1, field2...)
• 不唯一索引定义: AddNonUniqueIndex(field1, field2...)
• 创建表: CreateTableSQL() / CreateAll() (含子访问器)
• 获取创建脚本: GetCreateTableSQL() (含外键)
• 数据库结构相关的设置，一方面用来创建表，另一方面用来检测差异。

---

2. TableAccessorBase 角色

封装一张表的 CRUD + 查询构建 + 条件控制流。

2.1 生命周期

• 简版构造: new TableAccessor<MySchema>() → 需调用 .InjectDao(dao) （建立在RootBase里面不需要调用）
• 完整构造: new TableAccessor<MySchema>(dao) 内部自动注入
• 子访问器递归注入: InjectDao 利用反射发现成员类型实现 ITableAccessor

2.2 结构相关

• SchemaCheck(theSchemas) 单表结构检查
• SchemaCheckAll(theSchemas) 递归子访问器
• 主键定义: AddPKey(field1, field2...)
• 外键定义: AddFKeys(parentAccessor).Add(parentField, childField)
• 数据库结构相关的设置，一方面用来创建表，另一方面用来检测差异。

2.3 查询模式

经典返回 (Result/ResultList):

• FindClassic(where, order?) / FindAllClassic(where, order, top?)
• 自定义投影: FindAllCustomClassic(s => new { s.Id, ... }, where, order) 回调模式:
• FindAllBase((schema,row)=> {...})
• 链式: From().Where(...).Select(...).Run<T>() 行实体模式 (泛型):
• 使用 TableAccessor<MySchema, MyRow> 简化 Fill__Row 调用。

2.4 CRUD

• Insert: Insert(lets...) / Insert<Args>(argsLambda) / InsertObj(args, append?, except?)
• Update: Update(where, lets...) / UpdateObj(args, appendLets, matchedWhere)
• Delete: Delete(where) / DeleteSql(where)
• InsertOrUpdate: 多重重载 → 传入 where + 通用赋值 + onlyInsert + onlyUpdate

2.5 条件与流程控制

IfExists(where, trueSql, falseSql)
IfNotExists(where, trueSql, falseSql)
Raiserror(text)
IfExistRaiserror(where, text)
IfNotExistRaiserror(where, text)

用于在批量脚本中强制前置校验 (降低回滚成本)。

2.6 批量插入

InsertList(list, item => new[]{ field1 == v1, field2 == v2 }) → 单条多值 Insert。 注意行数上限 (~1000) 超出需拆分。

2.7 UpdateObj 详解

UpdateObj(args,
 append => new[]{ Price == (Price + 1) },
 match => new { args.Id, match.CustomWhere })

• match 返回匿名对象: 成员是条件列或 SqlWhere / SqlEqualOrLet；其他同名参数成员被排除赋值。

2.8 InsertObj 详解

InsertObj(args,
 append => new[]{ Created == nowVar },
 except => new { args.NoNeedField })

• except 匿名对象仅用于排除: 值不读取。

---

3. RowEntity

3.1 定义

public class WareRow : RowEntity<WareSchema> {
 public int Id;
 public string Name;
 public decimal Price;
}

3.2 填充

默认通过 FillByMyself__Row 同名映射; 可重写 Fill__Row(schema, reader) 自定义。

3.3 快速创建

WareRow.Create__Row(schema, reader) 静态构造并填充。

---

<a id="rootbase"></a>

4. RootBase

4.1 作用

聚合多个表访问器成为应用数据入口与结构管理中心。

4.2 注入与遍历

• 构造时/调用 InjectDao(dao) 遍历所有 ITableAccessor 成员注入 Dao。所以当按照规则构建逻辑树之后，在别处就不需要调用InjectDao了。

4.3 结构构建与检查

• SchemaCheck(schemas) → 首次检测差异
• SchemaRedundant(schemas) → 多余表/列/外键枚举
• GetCreateTableSQL() → 生成全部表 + 外键创建脚本 (IF NOT EXISTS 包装)

4.4 初始化

Create() 依次调用每个访问器的 CreateAll() → 自定义数据初始化 (如缓存行、预插入枚举值)。

4.5 统一执行代理

根对象提供 Execute/Select/From 快捷转调，简化上层依赖注入。

5. 常见问题

问题	场景	解决
未注入 Dao	简版构造后直接调用查询	调用 .InjectDao(dao)
行实体字段未填充	字段名不匹配或为属性带 set 限制	检查大小写 / 可写性
InsertObj 条件错用	match 匿名对象成员非列	返回对应列或 SqlWhere

---

返回目录

DaoFrom 链式查询详解

DaoFrom<TSchema> 是构建多表/多条件/排序/分组查询的 DSL 入口, 提供流式 API。

1. 启动入口

• dao.From<Schema>(alias?, topCount?, isDistinct?)
• dao.FromLimit<Schema>(alias?, startRow, rowCount) 分页
• accessor.From(topCount) / accessor.From((start,count))

2. Join 操作

支持: InnerJoin<T>, LeftJoin<T>, RightJoin<T>, FullJoin<T> 模式:

var q = dao.From<A>("a")
 .InnerJoin<B>("b").On((a,b)=> a.Id == b.AId)
 .LeftJoin<C>("c").On((a,c)=> a.Code == c.Code);

限制: 通常≤5表, 避免组合爆炸与性能下降。

3. 条件与组合

3.1 Where

.Where(a => a.Price >=1 & a.Name.LikeAll("水"))
.Where(a => a.Store >0) // 多次调用 AND 叠加

3.2 On

每个 Join 后必须跟 On; 多条件: (s1,s2)=> s1.Id == s2.Id & s2.Flag == 1

3.3 Group / Having

.Group(s => new { s.TypeId })
.Having(s => (s.Price * s.Store).ToSum() > 100)

3.4 Order

.Order(s => s.Created.Desc() + s.Id.Asc())

4. Select 投影

形式:

1. 单列: .Select(s => s.Id)
2. 匿名对象: .Select(s => new { s.Id, s.Name, Total = s.Price * s.Store })
3. 多表匿名: .Select((s1,s2)=> new { s1.Id, s2.Name })
4. 表达式列: 直接使用 By/Case 结果。 最后一次 Select 覆盖前一次。

5. 执行方法

• .Run<T>() → 自动反射同名映射到 List<T>
• .RunFirst<T>() → 单行 (空返回 Item == null)
• .Fill(list) / .FillFirst(container) → 直接填充现有集合/对象
• .Run(reader => ...) 自定义委托

6. 分页策略

FromLimit(start,count) → OFFSET/FETCH 或内部行号实现。 大偏移建议: 改用主键游标 (上一页最大值)。

7. 错误定位与调试

• 打印生成 SQL: 通常 SqlSelect.ToSql(true)
• 条件缺失: 检查是否调用 .Where
• 列重复: 为冲突列添加别名 field / "Alias"
• 空集合: 确认测试数据库中是否有满足条件数据

8. 性能建议

• 仅投影使用字段: 避免 Select *
• 合理使用 Top/Limit 控制返回规模
• 多 Join 时确保索引可用 (外键列 + 过滤列)

9. 示例汇总

var rows = dao.From<ProductSchema>("p", topCount:50)
 .LeftJoin<CategorySchema>("c").On((p,c)=> p.CategoryId == c.Id)
 .Where(p => p.Price >=10 & p.Name.LikeAll("茶"))
 .Order(p => p.Price.Desc())
 .Select((p,c)=> new { p.Id, p.Name, Cat = c.Name, Total = p.Price * p.Stock })
 .Run((s,r) => new { Id = r[s.Id], Name = r[s.Name], Cat = r[s.Cat], Total = r[s.Total] });

---

返回目录

Sql 组成类详解

用于构造可执行 SQL 片段与完整语句的对象集合: Select / Insert / Update / Delete / Merge / 条件 / 分组 / 排序等。

1. 核心接口与基类

• ISqlInterface 统一 ToSql(bool safe) 生成 SQL 文本。
• 各片段对象内部维护相关 Field/Where 列表。

2. 查询构造类

类	用途	关键成员
SqlSelect	单/多表查询	Fields, Wheres, Orders, Groups, TopCount, Distinct
SqlSelectByJoin	多表 Join 查询	Join 列表 + 条件 + 投影
SqlSelectRange	范围分页	起止行处理逻辑
SqlSelectCollection	组合多个 Select	聚合执行

3. 条件与逻辑

类	功能
SqlWhere / SqlWhereAnd / SqlWhereOr	条件树 (AND/OR)
SqlTextLike / SqlTextRange	文本模糊/区间
SqlNumericRange / SqlDateRange	数值/日期区间
SqlEqualOrLet	等值或赋值 (WHERE / SET 通用)

运算符直接产生 SqlWhere 或 SqlEqualOrLet 实例。可通过 & 和 | 组合。

4. 字段集合与排序

• SqlFields: Select 投影集合
• SqlOrders: 排序集合
• SqlGroups: 分组集合
• SqlOrder / SqlOrderItem: 单个排序方向控制 (Asc/Desc)

5. DML 语句对象

类	用途	特点
SqlInsert	插入	Add(SqlEqualOrLet) 收集列值
SqlInsertOrUpdate	合并	where 决定更新或插入
SqlUpdate	更新	NoWhere 决定是否必须 where
SqlDelete	删除	支持 where 判空
SqlMerge (若存在)	复杂合并	多条件 + 输出子句
SqlInsertByList	多行单语句插入	减少往返
SqlInsertBySelect	Insert + Select 投影	数据迁移/复制

6. 聚合与运算辅助

类	说明
SqlDivideOrSet	表达式除或赋值操作
SqlSubtractList	相减或连接
SqlEqualOrLet	相等或赋值
SqlLets	多赋值统一管理

7. Join 支持

• SqlJoinBlock 维护多个 Join 关系 (表别名/类型/On 条件)
• EmSelectJoinMode 枚举 Join 类型 (Inner/Left/Right/Full)

8. 内容与错误包装

• SqlContent 聚合多个 SQL + 变量列表 + 错误集合
• SqlContentErrorItem 错误项 (Message / Source)
• 通过 dao.Execute(SqlContent) 自动执行并写入错误

9. 变量声明与替换

• SqlHelper.VarsDeclare(vars) 生成 DECLARE 与 SET 语句前缀
• 与 CodingVar/CVar* 配合

10. 安全与可读性

• sql构建过程都做了防注入处理，仅个别方法有风险（如直接拼接字符串）。
• Update/ Delete 默认要求 where 条件，防止误操作全表更新/删除。
• ToSql(true) 生成格式化 SQL 便于阅读与调试。
• 可通过打印 SQL 语句检查生成结果。
• 执行前可检查 SqlContent 错误集合，避免运行时异常。

11. 示例

var upd = dao.NewUpdate(noWhere:false);
upd.Add(user.Name == "Alice", user.Age == 30);
upd.Wheres.Add(user.Id == 1001);
var run = dao.Run(upd.ToSql(true)).Execute();

var ins = dao.NewInsert();
ins.Add(prod.Id == 100, prod.Name == "茶", prod.Price == 12.5m);
var res = dao.Run(ins.ToSql()).Execute();

12. 常见问题

问题	原因	对策
Update 无 where	安全标记阻止执行	传入 noWhere:true 仅在确认为全表更新时使用
InsertOrUpdate 始终更新	where 不唯一匹配多行	改为主键或唯一索引列组合
拼接值 SQL 注入风险	未过滤用户输入	引入参数化层或严格白名单

---

返回目录

SqlWhere 与运算符语法详解

1. 概述

SqlWhere 表示一个可组合的条件树。通过对 Field 的运算符重载迅速构建。

2. 基础比较

表达式	结果
field == 10	等值判断 (支持数字/字符串/变量/子查询)
field != varNum	不等判断
field > otherField	大于
field <= 100	小于等于
field == DBNull.Value	IS NULL
field != DBNull.Value	IS NOT NULL

内部生成: SqlEqualOrLet 或 SqlWhere(单) 对象集合。

3. 文本匹配

name.LikeAll("abc")   // %abc%
name.LikeStart("abc") // abc%
name.LikeEnd("abc")   // %abc

可组合: (name.LikeAll("水") | name.LikeStart("矿")) & (price >= 1)

4. 逻辑运算

• where1 & where2 → AND
• where1 | where2 → OR 构造链: w &= next / w |= next (内部通过重载 &= / |= 或表达式临时对象)

5. 数值/日期范围

无专用方法时手动:

var range = (dateField >= startDate) & (dateField <= endDate);
var amountRange = (money >= 10) & (money <= 1000);

6. 子查询比较

var sub = dao.NewSelect();
// 构造子查询 select ( ... )
var cond = user.Id == sub; // 生成 Id = (subquery)

7. 组合策略

• 优先使用 AND 将过滤范围收紧，再 OR 扩展业务分支。
• 避免过度嵌套 (≥5层) 增加解析与数据库优化难度。

8. 调试与打印

var where = user.Name.LikeAll("A") & (user.Age >=18);
Console.WriteLine(where.ToString()); // 观察最终片段

若生成语句异常 → 检查字段是否被正确注册 (TableSchema 构造)。

9. 安全注意

• Like 模式中不要直接拼接用户原始输入, 需清洗 (去除 % _ 单引号) 或使用参数化。
• 数值比较请确保输入可转为合法数值。

10. 示例整合

var where = (prod.Price >=10 & prod.Price <=100)
    & (prod.Name.LikeAll("茶") | prod.Name.LikeAll("水"))
 & (prod.Deleted == (DBNull.Value));
var rows = dao.From<ProductSchema>()
 .Where(s => where)
 .Select(s => new { s.Id, s.Name, s.Price })
 .Run(r => new { Id = r[s.Id], Name = r[s.Name], Price = r[s.Price] });

11. 常见问题

问题	原因	对策
运算符组合结果不正确	逻辑优先级误解	使用括号明确分组
子查询返回多列	构造 Select 投影错误	子查询必须只返回单列
NULL 判断失效	使用 == null	使用 == (DBNull.Value)

---

返回目录

Schema 检测与结构同步详解

1. 目标

确保代码定义 (TableSchema) 与数据库实际结构一致, 在启动或部署阶段快速发现差异并给出修复脚本。

2. 结构抽取

Schemas.Create(dao) 提取当前数据库:

• 表集合: SchemaTables
• 列集合: SchemaColumns
• 索引: SchemaIndex
• 外键: SchemaFKs

3. 检测流程

var schemas = Schemas.Create(dao);
var diff = root.SchemaCheck(schemas.Item);
if(diff.Description.Length != 0) { /* 处理 */ }

顺序:

1. 表与列差异
2. 关系(FK)差异
3. 索引差异 (若实现)

4. 差异结果 SchemaCheckResult

字段	说明
CheckType	差异类别 (表/列/关系/索引)
Description	差异详情文本 (空表示无差异)
CreateText	建议补救 SQL (IF NOT EXISTS + CREATE / ALTER)

5. 多余对象检测

root.SchemaRedundant(schemas) 返回列表:

• 多余表
• 多余列
• 多余外键 需人工确认是否删除。

6. 自动修复策略

• 仅添加缺失对象 (表 / 列 / 外键 / 索引)
• 类型不匹配需人工确认 (可能涉及数据截断 / 迁移)
• 外键添加需保证被引用表与列已存在并建立索引

7. 生成创建脚本

root.GetCreateTableSQL() 合并所有表与外键的 IF NOT EXISTS 包装脚本。 执行:

var script = root.GetCreateTableSQL();
var res = dao.Run(script).Execute();

8. 安全与版本策略

• 首次部署: 直接执行全部 CREATE
• 升级: 检测差异后按顺序: 列 → 索引 → 外键
• 大规模结构改动: 先备份数据库, 再执行 ALTER

9. 常见问题

问题	原因	方案
差异返回空但实际表缺列	缓存或抽取失败	重试 Create 并确认连接字符串
CreateText 空	检测描述非空但未生成脚本	检查 TableSchema 定义是否完整
外键创建失败	目标列无索引或类型不匹配	先补列/索引再执行 FK 创建

10. 建议

• 在 CI/CD 中加入 SchemaCheck 步骤
• 对于频繁迭代, 使用脚本版本号表记录执行历史
• 现在有基于 SqlEntity 创建的数据库迁移工具可选用，可以用来生成数据库升级程序。

---

返回目录

参数与约束 Attribute 详解 (AccessorArgs)

1. AccessorArgs 模型定位

用于封装编辑/提交时的参数集合, 通过 Attribute 声明验证规则、默认值、展示标题等。

2. 常用 Attribute 列表

Attribute	作用
CArgsCaption	显示标题 (UI / 日志)
CArgsBanNull	禁止为 null
CArgsBanEmpty	禁止空字符串
CArgsBan0	数值不允许为 0
CArgsNoData	排除成员 (不参与填充)
CArgsDefaultValue	设置默认常量值
CArgsDefaultSqlServerTime	默认值为服务器当前时间
CArgsIntegerInList / Double / TextInList	值域限定列表
CArgsNumericMinMax / TextMinMax / DateMinMax	范围约束
CArgsPriceValid / CArgsMoneyValid	金额/价格格式校验
CArgsValid	自定义综合校验入口
CArgsNoEdit	标记不可编辑 (更新时忽略)

3. 验证流程顺序

1. 收集成员 (排除 [CArgsNoData])
2. 默认值填充
3. 空值与 0 排除
4. 范围与列表校验
5. 金额/价格特殊校验
6. 自定义校验 (CArgsValid) 失败时立即返回错误文本。

4. 示例

public class WareArgs : TableAccessorArgs {
 [CArgsCaption("名称")]
 [CArgsTextMinMax(1,50)]
 public string Name { get; set; }

 [CArgsPriceValid]
 [CArgsBan0]
 public decimal Price { get; set; }

 [CArgsDefaultSqlServerTime]
 public DateTime Created { get; set; }

 [CArgsIntegerInList(1,2,3)]
 public int Type { get; set; }
}

写入:

var res = ware.InsertObj(new WareArgs{ Name="水", Price=3.5m, Type=2 }, null, null).Execute();

5. 与 UpdateObj/InsertObj 的配合

• Args 实例传入自动按成员名称匹配列并生成赋值语句
• 被 [CArgsNoEdit] 标记成员在 UpdateObj 中应被排除 (根据 matchedWhere 或 except 参数)

6. 自定义校验扩展

CArgsValidAttribute 可封装委托或重写方法 (若设计上支持)。 策略: 尽量保持无副作用，只做纯数据校验。

7. 常见问题

问题	原因	方案
默认时间为本地时间	未使用 CArgsDefaultSqlServerTime	改用服务器时间 Attribute
列名不匹配赋值失败	Args 成员名称与列不同	使用对象映射前重命名成员
更新覆盖只读列	忽略 CArgsNoEdit	在 matchedWhere/except 中排除

---

返回目录

通用辅助类型详解

1. Conversion

提供安全的类型转换封装 (来源可能为 object / DBNull):

• ToInteger(obj) / ToLong(obj) / ToDecimal(obj)
• ToDate(obj) / ToString(obj) / ToBoolean(obj) / ToByte(obj)
• 策略: 遇到不可转换或 DBNull 返回默认值 (0, 0M, DateTime.MinValue, 空串)。

2. Strings

常见字符串操作支持 (格式化/拼接/清洗)。 一般情况下，正常使用它，都是安全的。

3. Result / ResultList

见核心对象章节。

4. SortableBindingList

用于 WinForm 或其它 UI 层的可排序集合。

5. PasswordHelper

封装密码/哈希/加密相关辅助 (若实现):

• 典型: CreateSalt(), HashPassword(password, salt)
• 应用层确保不在日志输出明文。

6. Operators (内部)

CompareString(left,right,ignoreCase) → 简化 VB 风格 Compare 用法。

7. ValueContainer<T>

用于链式 API 输出 (例如 .Find(out container, ...)).

8. 使用策略

• UI 层避免直接操作 DataRow, 使用 RowEntity / Args + Conversion 兼容。
• 对外部输入统一使用 Strings 的清洗方法 (若存在)。

9. 常见问题

问题	原因	方案
转换后出现默认值	数据源为 DBNull	使用可空类型获取再判断
排序失效	BindingList 未实现 IBindingListView	使用 SortableBindingList

---

返回目录

编码与编号生成 (Coding* 系列) 详解

1. 目标

统一生成符合业务规则的主键/单据号/序列值, 避免并发冲突。

2. 主要方法 (DAO_New.cs)

方法	格式	用途
NewBillId	头 + yyyyMMdd + 顺序	每日单据号/流水号
NewId14	2位头 + 年月日(7位编码) + 5位序号	稳定长度业务主键
NewId12	2位头 + 年月日(5位编码) + 5位序号	较短主键
NewId10	2位头 + 年月日(4位编码) + 4位序号	流水轻量标识
NewId	头 + 固定长度序号	一般用途
NewNumber / NewNumberLong	数值列最大值+1	简单递增
NullId	在范围内查找最小空闲位	补洞策略

3. 编码细节

• 年月日压缩: month*32 + day 保证唯一 (避免分隔符)
• 长度检查: 超过表示范围返回错误文本
• 并发注意: 高并发下建议包装事务或使用数据库 SEQUENCE (若未来扩展)

4. CodingVar 与变量声明

var vars = new[]{ new CVarInt("Index", false), new CVarText("Code", 20) };
var decl = SqlHelper.VarsDeclare(vars);

配合复杂脚本 (循环/查找) 构造临时变量。

5. NullId 场景

适用于需要填补中间空缺编号 (例如被删除的资源位)。性能注意:

• 搜索上限 99999
• 较大空间建议改用外部批量扫描或维护空闲表

6. 推荐策略

场景	方法
日志/流水单据	NewBillId
一般业务主键 (含日期信息)	NewId14 / NewId12
轻量序列	NewId10
纯数值增量列	NewNumber
空位补齐	NullId

7. 常见问题

问题	原因	对策
返回空串	参数非法或超界	检查长度范围 (1~17)
序号溢出	当天单据量超范围	增加序号长度或换更长编码方式
并发重复	多线程同时读取 max	引入行锁或升级 SEQUENCE

---

返回目录

扩展应用层 (Report / Set / Power / Function)

1. Report 报表系列

核心类:

• CReportGen / CReportGenExecuter: 报表生成流程 (字段收集 / 数据拉取 / 输出)
• ExcelHelper / dgtToExcel: 导出到 Excel
• 动态列/状态: CReportGenTag, CReportGenStateItem 使用模式:

1. 构建报表定义 (列/筛选参数)
2. 运行执行器填充数据集
3. 选择输出 (Excel / 内存对象)

2. Set 设置系列

• CSetBase, CSetModel: 设置项模型与存取包装
• 派生类型: CSetText, CSetReal, CSetMoney, CSetInt, CSetIntEnum, CSetBool 用途: 统一管理系统参数 (默认值, 动态变更, 持久化)。

3. Power 权限

• CPower, CPowerItem, CPowerExecuter 实现权限点定义与检测
• CPowerModel 持久化用户/角色权限集合 策略: 业务调用前 Executer.Check(permissionCode) 决定可执行性。

4. Function 功能封装

• CFunction, CFunctionBase 抽象可执行业务操作单元
• 可与权限 / 菜单 / 报表组合形成模块化执行界面

5. 使用建议

模块	建议
报表	分离数据层与展示层, 大型报表分页导出
设置	建立缓存层减少数据库读取频率
权限	设计细粒度枚举 + 角色策略 (避免硬编码字符串)
功能单元	封装输入/输出 DTO 与事务边界

6. 常见问题

问题	原因	方案
报表内存过大	一次取全量数据	增加分页/流式写出
设置变更不生效	缓存未刷新	引入失效事件或时间戳
权限绕过	未集中校验	在 Root 层统一拦截权限验证
功能逻辑难测试	混合 UI/数据	拆分纯业务方法与界面交互层

---

返回目录

条码与杂项工具

1. 条码/二维码系列

类	功能
CEAN13	生成 EAN13 条码 (校验位计算)
CCode128	Code128 编码
CCode93	Code93 编码
CQRCode	二维码生成
CPOS	POS 相关辅助 (票据格式等)

使用要点

• 尽量在服务端生成位图/向量并缓存
• 参数校验 (长度 / 字符集) 在输入阶段完成

2. PinYin

• 汉字转拼音首字母, 用于快速检索或简易排序, 支持多音字处理。

3. UI / 展示模型

类	说明
ModelObject	通用数据承载实体
ViewItemBase	视图项基类
CItemView	列表项展示模型

4. 使用策略

• 条码生成前清洗内容 (去除非法字符)
• 大批量生成使用并行与缓存避免重复计算校验位
• 拼音转换结果可缓存到字段减少重复调用

5. 常见问题

问题	原因	方案
条码识别失败	分辨率过低/反差不足	增加输出 DPI / 调整前景背景色
二维码过大	存储数据超规格	采用短链接或外部ID引用

---

返回目录

性能与集合支持详解

1. 分层拆分

• DAO 按功能拆分 (Select/Execute/Find/New) 降低单文件复杂度 → 更易维护

2. 查询性能

• 投影最少列 (避免 SELECT *)
• 使用表达式列 (By) 代替物理冗余字段
• 大数据分页: 主键范围滚动 vs 大 OFFSET

3. 写入性能

场景	建议
批量插入 ≤1000 行	InsertList / SqlInsertByList
批量插入 >1000 行	拆分批次 + 事务分段
合并插入更新	InsertOrUpdate 或 Merge

4. 事务控制

• 小事务: 单条语句 (ExecuteNoTrans 或 Execute)
• 大事务: 聚合多条 SqlContent + 一次提交
• 长事务风险: 锁范围扩大 → 建议拆分逻辑

5. 缓存与重用

• TableSchema 与 Field 对象单实例复用 (根对象聚合)
• 频繁表达式列缓存实例 (避免重复构造)

6. 映射策略

方式	优点	缺点
DataTable	快速/通用	内存占用高
Reader + 回调	低内存高性能	需手写映射逻辑
RowEntity	复用字段定义	反射存在开销
匿名 Select + Run	灵活/较快	需要匹配成员名

7. 索引与统计

• 针对 Where/Join/Order 中常用列建立索引
• 批量导入前可暂时禁用非必要索引 (若实现) 再重建

8. 锁与并发

• 避免长时间持有事务锁 (减少交互/等待)
• 编号生成可加行锁或使用 SEQUENCE (扩展方向)

9. 监控建议

• 记录执行 SQL + 时长 + 行数
• 分析慢查询 (执行计划 / 缺失索引)

10. 常见问题

问题	原因	方案
查询慢	无索引 / 过度列返回	添加覆盖索引 / 精简投影
插入阻塞	大事务锁竞争	拆分批次 / 降低并发
内存飙升	使用 DataTable 处理巨量行	改用 Reader 回调模式
编号冲突	并发读取 max	使用悲观锁或改为自增列

---

返回目录

待补充章节详细内容 (整合版)

此文件整合各“待补充”主题的方向与规划, 提供后续扩展蓝图。

1. FieldSql* 动态表达式扩展

计划补充:

• 聚合表达式 (SUM/AVG/MAX/MIN) 的 FieldSql 封装 (这些都在 FieldSqlDecimal、FieldSqlInt 及 FieldSqlNumeric 中实现了)
• 条件聚合 + Over 子句支持 (窗口函数) 若底层允许 （TableSchema.By 当中实现了 RowNumber ）

2. DaoFrom 高级节点

• 支持自动分页统计总数 (Count() 附加第二条语句)
• Having 聚合封装: g => Price.ToSum() > 100 (可以这样实现)
• 动态 Join 条件缓存与复用

3. Schema 自动修复增强（已具备基础能力）

当前通过 RootBase.SchemaCheck(schemas) 返回的差异结果即可区分并处理：

• 缺失对象: 表 / 列 / 外键 / 索引 → 可直接生成创建脚本
• 类型/属性不匹配: 列类型、长度、可空、自增 → 需要人工确认后执行 ALTER
• 冗余对象: 未在代码定义的表/列/关系 → 人工审查是否清理 现有差异分类可映射到之前列出的枚举: AddMissingTable / AddMissingColumn / ColumnTypeMismatch / MissingFK / MissingIndex / RedundantObject。自动修复策略可直接依据结果进行“安全(添加)”与“提示(类型变更)”分级处理；“危险(删除)”仍需人工确认。后续仅考虑：
• 合并多差异脚本为事务分批执行
• 生成差异报告 JSON 供 CI 分析

4. Attribute 验证增强

• 组合验证 Attribute (多条件聚合)
• 国际化消息 (多语言错误文本资源)
• 批量验证报告 (一次返回全部失败项)

5. 事务与错误聚合策略

• 分段提交: 超长批次内部拆分 N 条写入一段事务
• 回滚分析: 捕获数据库错误码→ 映射业务可读错误

6. 多表 Join 性能进一步建议

• 自动检测缺失索引并提示
• Join 顺序优化 (基于行数估计) 若引入统计

7. 分页策略扩展

• 统一分页 DTO: { Items, PageIndex, PageSize, TotalCount }
• Keyset Pagination 支持: 依据最后一条主键值继续查询下一页

8. SqlMerge 场景深入

• 支持输出变化行清单 (Inserted/Updated)
• 冲突策略枚举 (优先源/优先目标/跳过)

9. 安全与参数化 (已评估后取消)

当前 Insert/Update/Delete通过字段赋值 (Field == 值 / .Let()) 已形成受控构造,现阶段不再引入额外命名参数体系。

10. 日志与诊断

• Hook: 执行前/后事件 → 可注入 APM (如 OpenTelemetry)

11. 分布式/多数据库

• 多数据源路由: 读写分离, 主从延迟检测
• 失败重试策略 (幂等写入)

12. 版本迁移框架

• Migration 脚本表: 记录执行时间/版本号/脚本内容
• 回滚脚本登记规范

13. 异步与并行

• 全面补充 Async 系列 (当前部分已有 SelectAsync / ExecuteAsync)
• 批量并行查询聚合结果 (限制连接池压力)

14. 可观测性

• 统计: 执行次数 / 错误率 / 平均耗时 / 最大耗时
• 输出 JSON 指标供外部监控抓取

---

返回目录

分节文件索引

本索引列出 readmelist 下的所有详细说明文件。

序号	文件	简介
01	01-core-dao.md	DAO / Result / 变量容器详解
02	02-fields.md	字段类型与表达式列说明
03	03-accessors-root.md	访问器/行实体/根对象
04	04-daofrom.md	DaoFrom 链式查询 DSL
05	05-sql-objects.md	Sql 组成类与 DML 对象
06	06-sqlwhere-operators.md	条件与运算符语法
07	07-schema-sync.md	Schema 检测与同步
08	08-attributes.md	参数与验证 Attribute
09	09-common-utils.md	通用辅助与转换工具
10	10-coding-ids.md	编号与编码生成体系
11	11-application-layer.md	报表/设置/权限/功能层
12	12-barcodes-utils.md	条码与杂项工具
13	13-performance.md	性能与集合支持策略
14	14-future-topics.md	未来扩展与规划
15	api.md	总览 (主目录)

使用建议:

• 从 api.md 了解总体结构
• 根据需要跳转至对应详细文件
• 更新新模块后同步修改本索引

---

返回总览

与主 README 的关联

目标

说明如何在主 readme.md 中引用本 API 文档体系, 以及推荐的交叉跳转方式。

建议结构

在 readme.md 中加入如下片段:

## API 文档
详尽的框架 API 说明请参阅 `readmelist/api.md` 与分节文件:
- 核心对象: readmelist/01-core-dao.md
- 字段与表达式: readmelist/02-fields.md
- 访问器与根对象: readmelist/03-accessors-root.md
...

交叉链接示例

[DAO 深入说明](readmelist/01-core-dao.md)
[字段类型与运算符](readmelist/02-fields.md)

维护策略

场景	操作
新模块加入	在分节文件创建新说明并更新 15-index.md
废弃模块	在对应文件顶部标记 Deprecated 并从索引表移除
版本变更	更新每个文件底部的历史记录区块

版本 / 变更日志建议

每个分节文件最后添加:

---
**历史**
- 2024-12-17: 初版
- 2025-01-xx: 调整 Xxx 说明

自动化思路 (可选未来)

• 脚本扫描代码结构生成字段/方法列表 → 写入对应 markdown
• 使用 CI 在提交时校验索引与文件是否同步

---

返回总览

文档更新日志 (Docs Changelog)

日期	文件	内容概要
2024-12-16	api.md	初稿建立: 总览结构
2024-12-17	api.md	扩展: DAO / TableSchema / TableAccessorBase / RowEntity / RootBase / FieldInt
2024-12-17	api.md	第二次扩展: DaoFrom / 运算符 / 字段总览 /计算列 / Attribute 流程 / Schema 差异 / 性能建议
2024-12-17	多文件	按分节拆分创建 (01~16) 完成细化文档
2025-11-09	多文件	统一修正日期标记, 增补支持性文档说明与最新维护时间

##维护建议

• 每次功能开发完成后更新对应分节文件并在此记录日期/摘要。
• 大规模重构后添加“影响范围”描述。
• 删除模块需在日志中标记并说明迁移/替代方案。

---

返回总览

历史说明

本文档记录文档体系与框架结构的形成过程, 用于审计与回顾。

阶段 1: 初始设计

• 目标: 提供轻量 ORM 风格封装, 简化 CRUD 与结构检测。
• 核心: DAO + TableSchema + TableAccessor 基础建立。

阶段 2: 文档雏形

• 建立 api.md 总览, 列出重要类型。
• 逐步补充核心方法分组说明。

阶段 3: 深度细化

• 拆分 15+ 分节文档, 每节专注一个领域 (查询 DSL / Schema / 编号 / 性能)。
• 增加未来扩展规划 (参数化 / 统计 / 迁移框架)。

阶段 4: 规划与展望

• 引入异步全面化 / 参数化安全层。
• 增加 Migration 与监控指标。
• 可能扩展到多数据库读写分离与分布式事务。

审阅与迭代

• 建议每季度审阅性能与结构章节是否与源码一致。
• 对废弃 API 标记 Deprecated 并在 HISTORY 中注明。

---

返回总览