# 数据验证与过滤

<cite>
**本文引用的文件**
- [validate.js](file://public/static/js/validate.js)
- [jquery.validate.js](file://public/static/js/jquery.validate/jquery.validate.js)
- [additional-methods.js](file://public/static/js/jquery.validate/additional-methods.js)
- [AGENTS.MD](file://AGENTS.MD)
- [bootstrap.js](file://public/themes/default/public/assets/bootstrap5/js/bootstrap.js)
- [select.html](file://public/themes/admin_default/admin/route/select.html)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本指南聚焦 ThinkCMF 的数据验证与过滤机制，覆盖前端 jQuery Validation 插件的字段规则、远程校验、条件与批量验证，以及后端与前端协同的安全处理策略。同时结合项目规范文档中的富文本与输出转义要求，给出最佳实践与安全建议，帮助开发者构建健壮、可维护且安全的数据输入处理链路。

## 项目结构
- 前端验证主要依赖 jQuery Validation 插件，包含核心验证逻辑与附加规则集。
- 后端层面，项目规范强调对字段内容统一进行安全转义，富文本字段在入库与展示时分别进行 URL 替换与 HTML 转义处理。
- 主题与模板层提供安全渲染能力，例如 HTML 清洗工具用于过滤不受信任的富文本。

```mermaid
graph TB
subgraph "前端"
V["validate.js<br/>jQuery Validation 核心"]
AM["additional-methods.js<br/>附加规则"]
BJS["bootstrap.js<br/>HTML 清洗工具"]
end
subgraph "后端规范"
DOC["AGENTS.MD<br/>富文本与转义规范"]
TPL["select.html<br/>模板安全输出"]
end
V --> AM
V --> BJS
DOC --> TPL
BJS --> TPL
```

图表来源
- [validate.js:1-1246](file://public/static/js/validate.js#L1-L1246)
- [additional-methods.js:1-1056](file://public/static/js/jquery.validate/additional-methods.js#L1-L1056)
- [bootstrap.js:2989-3025](file://public/themes/default/public/assets/bootstrap5/js/bootstrap.js#L2989-L3025)
- [AGENTS.MD:427-445](file://AGENTS.MD#L427-L445)
- [select.html:1-47](file://public/themes/admin_default/admin/route/select.html#L1-L47)

章节来源
- [validate.js:1-1246](file://public/static/js/validate.js#L1-L1246)
- [additional-methods.js:1-1056](file://public/static/js/jquery.validate/additional-methods.js#L1-L1056)
- [bootstrap.js:2989-3025](file://public/themes/default/public/assets/bootstrap5/js/bootstrap.js#L2989-L3025)
- [AGENTS.MD:427-445](file://AGENTS.MD#L427-L445)
- [select.html:1-47](file://public/themes/admin_default/admin/route/select.html#L1-L47)

## 核心组件
- 前端验证引擎：负责规则解析、逐项校验、错误收集与展示，支持远程校验、条件依赖、范围与长度等内置规则。
- 附加规则集：提供更丰富的业务规则（如银行卡号、IBAN、手机号、正则表达式等）。
- 安全清洗工具：对富文本进行白名单过滤，移除危险标签与属性，保障输出安全。
- 后端安全策略：统一对字段内容进行 HTML 转义，富文本入库前替换媒体 URL 并二次转义，展示时再做解码与 URL 替换。

章节来源
- [validate.js:916-956](file://public/static/js/validate.js#L916-L956)
- [additional-methods.js:1-1056](file://public/static/js/jquery.validate/additional-methods.js#L1-L1056)
- [bootstrap.js:2989-3025](file://public/themes/default/public/assets/bootstrap5/js/bootstrap.js#L2989-L3025)
- [AGENTS.MD:427-445](file://AGENTS.MD#L427-L445)

## 架构总览
前端通过 jQuery Validation 对表单字段施加规则，实时反馈错误；对于需要跨域或复杂逻辑的校验，采用远程校验；后端在入库与展示阶段配合富文本 URL 替换与 HTML 转义，确保数据完整性与安全性。

```mermaid
sequenceDiagram
participant U as "用户"
participant F as "表单"
participant JV as "jQuery Validator"
participant R as "远程校验接口"
U->>F : 输入/提交
F->>JV : 触发校验
JV->>JV : 解析规则/依赖/范围
JV->>R : 远程校验(可选)
R-->>JV : 返回校验结果
JV-->>F : 展示错误/通过
F-->>U : 反馈与重试
```

图表来源
- [validate.js:936-994](file://public/static/js/validate.js#L936-L994)
- [jquery.validate.js:1330-1348](file://public/static/js/jquery.validate/jquery.validate.js#L1330-L1348)

章节来源
- [validate.js:936-994](file://public/static/js/validate.js#L936-L994)
- [jquery.validate.js:1330-1348](file://public/static/js/jquery.validate/jquery.validate.js#L1330-L1348)

## 详细组件分析

### 前端验证引擎（validate.js）
- 规则解析与归一化：支持从类、属性、元数据与静态规则集中合并规则，并对依赖、参数与数值范围进行标准化。
- 条件验证：通过依赖函数/选择器动态启用/禁用规则，避免无关字段触发校验。
- 远程校验：统一通过 AJAX 请求远程接口，依据响应状态与消息决定通过或失败，并维护并发请求计数。
- 错误展示：按容器/标签统一收集错误，支持高亮/反高亮与焦点定位，便于用户体验与调试。

```mermaid
flowchart TD
Start(["开始校验"]) --> Parse["解析并归一化规则"]
Parse --> DepCheck{"依赖满足?"}
DepCheck --> |否| Skip["跳过该规则"]
DepCheck --> |是| Run["执行规则方法"]
Run --> Remote{"是否远程校验?"}
Remote --> |是| Ajax["AJAX 请求并等待"]
Ajax --> Result{"校验通过?"}
Result --> |是| Next["继续下一个规则"]
Result --> |否| Err["记录错误并显示"]
Remote --> |否| Next
Next --> Done(["完成"])
Err --> Done
Skip --> Done
```

图表来源
- [validate.js:830-893](file://public/static/js/validate.js#L830-L893)
- [validate.js:936-994](file://public/static/js/validate.js#L936-L994)

章节来源
- [validate.js:830-893](file://public/static/js/validate.js#L830-L893)
- [validate.js:936-994](file://public/static/js/validate.js#L936-L994)

### 内置与附加规则（jquery.validate.js / additional-methods.js）
- 基础规则：必填、邮箱、URL、数值范围、步长等。
- 附加规则：信用卡号、IBAN、手机号、NIF/NIE、正则表达式匹配、忽略空白等。
- 自定义扩展：可通过 addMethod 注册新规则，并提供默认国际化消息。

```mermaid
classDiagram
class ValidatorMethods {
+required(value, element, param)
+email(value, element)
+url(value, element)
+min(value, element, param)
+max(value, element, param)
+range(value, element, param)
+step(value, element, param)
}
class AdditionalMethods {
+creditcard(value, element)
+iban(value, element)
+phoneUS(value, element)
+pattern(value, element, param)
+regularExpression(value, element, param)
}
ValidatorMethods <.. AdditionalMethods : "共同注册到 $.validator"
```

图表来源
- [jquery.validate.js:1330-1418](file://public/static/js/jquery.validate/jquery.validate.js#L1330-L1418)
- [additional-methods.js:264-373](file://public/static/js/jquery.validate/additional-methods.js#L264-L373)
- [additional-methods.js:726-734](file://public/static/js/jquery.validate/additional-methods.js#L726-L734)
- [validate.js:907-914](file://public/static/js/validate.js#L907-L914)

章节来源
- [jquery.validate.js:1330-1418](file://public/static/js/jquery.validate/jquery.validate.js#L1330-L1418)
- [additional-methods.js:264-373](file://public/static/js/jquery.validate/additional-methods.js#L264-L373)
- [additional-methods.js:726-734](file://public/static/js/jquery.validate/additional-methods.js#L726-L734)
- [validate.js:907-914](file://public/static/js/validate.js#L907-L914)

### 安全清洗与富文本处理（bootstrap.js / AGENTS.MD）
- HTML 清洗：基于白名单与允许属性列表，移除危险标签与属性，仅保留安全节点。
- 富文本入库/展示：入库前对富文本进行 URL 替换与 HTML 转义；展示时再做解码与 URL 替换，避免 XSS 与路径泄露。

```mermaid
flowchart TD
In(["富文本输入"]) --> Clean["HTML 清洗(白名单/属性过滤)"]
Clean --> Replace["URL 替换(相对路径/CDN)"]
Replace --> Escape["HTML 转义"]
Escape --> Save["入库"]
Save --> Show["展示前解码与URL替换"]
Show --> Out(["安全输出"])
```

图表来源
- [bootstrap.js:2989-3025](file://public/themes/default/public/assets/bootstrap5/js/bootstrap.js#L2989-L3025)
- [AGENTS.MD:427-445](file://AGENTS.MD#L427-L445)

章节来源
- [bootstrap.js:2989-3025](file://public/themes/default/public/assets/bootstrap5/js/bootstrap.js#L2989-L3025)
- [AGENTS.MD:427-445](file://AGENTS.MD#L427-L445)

### 模板与输出安全（select.html）
- 模板中对 URL 参数进行安全转义，避免注入与路径拼接风险。
- 在路由生成与占位符处理时，确保参数与标签的正确性与安全性。

章节来源
- [select.html:1-47](file://public/themes/admin_default/admin/route/select.html#L1-L47)

## 依赖分析
- validate.js 依赖 jquery.validate.js 的基础规则与远程校验框架，并通过 additional-methods.js 扩展业务规则。
- bootstrap.js 的 HTML 清洗工具与 AGENTS.MD 的富文本处理规范形成互补，分别覆盖前端渲染与后端存储/展示两个关键环节。
- 模板层 select.html 体现对输出安全的重视，配合后端转义策略共同降低风险。

```mermaid
graph LR
JV["jquery.validate.js"] --> V["validate.js"]
AM["additional-methods.js"] --> V
BJS["bootstrap.js"] --> TPL["select.html"]
DOC["AGENTS.MD"] --> TPL
DOC --> BJS
```

图表来源
- [validate.js:1-1246](file://public/static/js/validate.js#L1-L1246)
- [jquery.validate.js:1-1418](file://public/static/js/jquery.validate/jquery.validate.js#L1-L1418)
- [additional-methods.js:1-1056](file://public/static/js/jquery.validate/additional-methods.js#L1-L1056)
- [bootstrap.js:2989-3025](file://public/themes/default/public/assets/bootstrap5/js/bootstrap.js#L2989-L3025)
- [AGENTS.MD:427-445](file://AGENTS.MD#L427-L445)
- [select.html:1-47](file://public/themes/admin_default/admin/route/select.html#L1-L47)

章节来源
- [validate.js:1-1246](file://public/static/js/validate.js#L1-L1246)
- [jquery.validate.js:1-1418](file://public/static/js/jquery.validate/jquery.validate.js#L1-L1418)
- [additional-methods.js:1-1056](file://public/static/js/jquery.validate/additional-methods.js#L1-L1056)
- [bootstrap.js:2989-3025](file://public/themes/default/public/assets/bootstrap5/js/bootstrap.js#L2989-L3025)
- [AGENTS.MD:427-445](file://AGENTS.MD#L427-L445)
- [select.html:1-47](file://public/themes/admin_default/admin/route/select.html#L1-L47)

## 性能考量
- 规则归一化与依赖评估在前端一次性完成，减少重复计算。
- 远程校验采用并发计数与请求去重，避免重复请求与竞态。
- HTML 清洗仅针对不可信输入，尽量在服务端完成，前端仅作兜底。
- 富文本处理建议在服务端进行，前端仅进行白名单过滤，兼顾性能与安全。

## 故障排查指南
- 远程校验失败：检查返回状态与消息格式，确认响应头与 message 结构一致。
- 依赖规则不生效：核对 depends 表达式或函数返回值，确保元素可见与依赖存在。
- 正则规则无效：确认正则字符串与转义，必要时使用附加规则中的正则方法。
- 富文本异常：检查入库前是否已替换 URL 并转义，展示时是否正确解码与还原。

章节来源
- [validate.js:936-994](file://public/static/js/validate.js#L936-L994)
- [validate.js:830-893](file://public/static/js/validate.js#L830-L893)
- [additional-methods.js:726-734](file://public/static/js/jquery.validate/additional-methods.js#L726-L734)
- [AGENTS.MD:427-445](file://AGENTS.MD#L427-L445)

## 结论
ThinkCMF 的数据验证与过滤体系从前端规则与远程校验到后端富文本处理与模板安全输出形成闭环。通过合理使用 jQuery Validation 的规则与远程校验能力，结合 HTML 清洗与统一转义策略，可以有效提升数据完整性与安全性。建议在实际项目中将安全策略前置到服务端，前端仅作为增强体验与快速反馈手段。

## 附录
- 常用规则速查：必填、邮箱、URL、数值范围、步长、信用卡、IBAN、手机号、正则、忽略空白等。
- 最佳实践：服务端优先、前端辅助；富文本入库前 URL 替换与转义，展示时解码与还原；模板输出严格转义；远程校验统一返回结构化消息。