069. 通用模块、动态查询与 AI 查询能力

学习目标

这一节开始进入通用模块设计。

学完后，你应该能理解：

• 为什么后台查询比增删改更难通用化；
• ORM 适合什么，不适合什么；
• 通用模块想解决哪些重复劳动；
• 动态字段、筛选、排序如何用配置驱动；
• AI 查询能力为什么需要强后端查询能力支撑。

后端查询为什么难

前端页面还有按钮、表单、弹窗和视觉反馈。

后端很多时候只有逻辑。

尤其是查询逻辑，复杂度会快速上升。

例如一个列表接口要支持：

• 大于；
• 小于；
• 等于；
• 包含；
• 不包含；
• 多值查询；
• 范围查询；
• 排除范围；
• 多字段排序；
• 聚合统计字段筛选。

如果每个业务表都手写一遍，代码量会非常大。

AI 查询需要结构化能力

AI 可以把自然语言转成查询条件。

例如：

查询项目预算小于 20 万或者大于 50 万的数据

最后仍然要落到结构化筛选条件上。

AI 负责理解用户意图。

后端负责安全、准确地执行查询。

如果后端只支持简单范围查询，AI 能表达的能力也会被限制。

ORM 的适用范围

ORM 很适合做基础增删改查。

比如：

• 新增用户；
• 修改项目；
• 查询单条记录；
• 删除一条数据；
• 把数据库行映射成对象。

这些场景里，ORM 能减少大量字段映射代码。

但一旦进入复杂查询、统计查询、动态排序，ORM 就会变得很绕。

通用模块的目标

通用模块想把常见后台能力抽象成配置。

目标不是只少写几行代码。

而是让一个模块只配置一次，就自动具备：

• 新增；
• 删除；
• 修改；
• 查询；
• 分页；
• 排序；
• 复杂筛选；
• 统计字段。

这样后续新增业务表时，不必重新写一整套 Controller、Service、DAO。

配置驱动字段

通用模块会读取字段配置。

字段是否出现在接口结果里，可以通过配置控制。

例如某个字段从配置里删除后，接口返回结果里也不再包含它。

再把字段加回配置，接口就重新返回这个字段。

这类能力对后台系统很重要。

因为很多后台页面都是表格。

表格字段、查询字段、排序字段经常变化。

配置驱动查询

字段配置不只是控制展示。

还会决定字段能不能参与查询。

例如金额字段可以支持：

• 大于某个值；
• 小于某个值；
• 范围查询；
• 排序。

当字段被纳入通用模块配置，它就可以共享通用查询能力。

这比每个接口手写一套筛选判断更稳定。

统计字段配置

项目已花费金额和余额不是普通字段。

它们来自统计计算。

通用模块通过配置 SQL 片段或子查询，把统计结果变成可查询字段。

例如：

• 从审批单表筛选已通过记录；
• 按项目 ID 分组；
• 对金额求和；
• 得到项目已花费金额；
• 再用预算减去已花费金额得到余额。

这样统计字段也能参与筛选和排序。

SQL 透明性

通用模块不是把 SQL 藏起来。

相反，它需要让 SQL 可控。

配置里的关联表、关联条件、子查询都应该能看见。

这样出问题时才能判断：

• join 是否正确；
• 子查询是否正确；
• 统计字段是否正确；
• 筛选条件是否走了预期字段。

对刚从 JS 转过来的开发者来说，这里要建立一个意识：后端抽象不能牺牲可调试性。

SQL 注入边界

动态查询不等于拼接不安全 SQL。

用户输入的值应该用参数化方式传入。

比如用户传了一个看起来像 SQL 注入的字符串，它也应该只被当作普通参数值。

前端可以拼筛选条件。

真正的 SQL 执行和参数绑定必须在后端完成。

这条边界不能混。

这一节的重点

这一节把通用后台模块的设计目标讲清楚。

你需要记住：

• 查询通常比增删改更难通用化；
• AI 查询能力依赖后端结构化查询能力；
• ORM 适合基础增删改查，不适合包办复杂统计；
• 通用模块用配置承载字段、筛选、排序和统计；
• 统计字段要在数据库层面生成，才能分页排序；
• 动态查询必须使用参数化执行，不能让前端拼完整 SQL。