本文讨论什么

以一款本地数据检索工具（下称“测试助手”）为例，讨论桌面应用如何划分职责、处理耗时任务、扩展数据源，并通过测试、日志和性能基线控制改造风险。文中的实现已抽象，不涉及内部业务、凭据或源码。

一、先明确问题，而不是马上写代码

软件设计的第一步不是选择框架，而是把问题说清楚。

早期工具通常从一个具体需求开始：连接数据源、执行查询、展示结果。随着功能增加，连接配置、查询逻辑、界面控件、消息解析和导出功能容易堆在同一个入口文件中。它可能短期内可以工作，但会逐渐出现几个问题：

1. 改一个功能会影响其他功能；
2. 界面线程承担了查询、解码和文件操作，操作时容易卡顿；
3. 新增一种数据源需要修改大量旧逻辑；
4. 错误信息不统一，问题难以定位；
5. 测试只能依赖手动点击，回归成本越来越高。

因此，我先把软件目标拆成四类：

• 连接：保存、编辑、验证和复用连接配置；
• 查询：执行查询、分批返回结果、支持取消和导出；
• 理解：对结构化或半结构化数据进行解析、格式化和检索；
• 工程化：日志、配置、测试、打包、更新和问题追踪。

拆分目标之后，架构设计就有了依据：每个模块应该围绕一个清晰职责展开，而不是围绕某个历史文件继续堆代码。

二、采用分层架构控制复杂度

测试助手采用桌面应用常见的分层思路，将界面、流程编排、领域服务、基础设施和公共模型分开：

Presentation
    ↓
Controller / Application
    ↓
Service / Domain
    ↓
Infrastructure

Common：模型、常量、错误类型和跨层通用能力

1. Presentation：只负责展示和交互

界面层包含主窗口、连接管理器、工作区、结果表格、详情面板、工具栏和状态提示。

它的职责是：

• 接收用户输入；
• 触发一个明确的应用操作；
• 展示加载、进度、结果和错误；
• 通过信号或回调接收后台任务结果。

界面层不直接连接数据库，也不负责解析复杂消息。这样做的好处是，界面布局变化不会迫使底层服务跟着修改。

2. Controller：负责把用户动作变成任务

Controller 负责把“点击查询”转换为一个可追踪的任务，并协调任务开始、进度、完成、失败和取消。

这里还需要一个统一的任务管理器。所有耗时操作都通过任务管理器提交，避免每个窗口各自创建线程，最终形成难以维护的线程网络。

3. Service：表达业务无关的技术能力

Service 层负责连接数据源、执行查询、处理分页、调用解码器和整理结果。它不依赖 Qt 控件，不直接修改界面。

例如，一个查询服务可以只关心：

输入：查询参数、取消令牌、结果回调
输出：批量结果、进度、完成状态或结构化错误

这种接口比“服务内部直接操作表格”更容易测试，也更容易在未来替换界面技术。

4. Infrastructure：隔离外部依赖

连接池、配置文件、系统密钥环、本地历史记录、日志、网络客户端和文件存储都属于基础设施层。

把外部依赖集中管理，可以避免数据库驱动、密钥存储和日志格式散落在各个界面文件中，也方便在测试环境中替换为受控实现。

三、连接池怎么设计

连接池是这类本地工具里很容易被低估的一层。最简单的做法是“全局保存一个连接”，但它通常无法同时处理并发查询、断线重连和线程安全问题。更稳妥的思路是：池负责连接的借还，Service 负责使用连接，UI 不接触连接对象。

1. 连接池的职责边界

一个通用连接池至少需要处理以下事情：

• 按连接配置创建有限数量的连接；
• 从池中借出可用连接；
• 任务结束后无论成功还是失败都归还连接；
• 发现连接失效时丢弃并补充新连接；
• 等待超时后返回明确错误，而不是无限等待；
• 应用退出时关闭全部连接；
• 不把密码和令牌放进普通连接对象的日志或 repr 中。

连接池的 key 应只包含经过规范化的非敏感连接参数，例如数据源类型、地址、端口和逻辑库名。密码从安全存储中按需读取，不参与日志和普通缓存的 key。

2. 一个通用的池化接口

下面是经过简化的 Python 结构示意。它没有绑定任何特定数据库，也不包含真实地址、账号或业务字段：

from contextlib import contextmanager
from queue import Empty, Queue


class ConnectionPool:
    def __init__(self, factory, *, min_size=1, max_size=4, wait_timeout=5):
        self._factory = factory
        self._available = Queue(maxsize=max_size)
        self._max_size = max_size
        self._wait_timeout = wait_timeout
        self._created = 0

        for _ in range(min_size):
            self._available.put(self._create())

    def _create(self):
        connection = self._factory()
        self._created += 1
        return connection

    @contextmanager
    def acquire(self):
        connection = None
        try:
            try:
                connection = self._available.get(timeout=self._wait_timeout)
            except Empty as exc:
                raise TimeoutError("连接池等待超时") from exc

            if not self._is_alive(connection):
                self._close_safely(connection)
                connection = self._create()
            yield connection
        except Exception:
            if connection is not None and not self._is_alive(connection):
                self._close_safely(connection)
                connection = None
            raise
        finally:
            if connection is not None:
                self._available.put(connection)

    def _is_alive(self, connection):
        try:
            connection.ping()
            return True
        except Exception:
            return False

    def _close_safely(self, connection):
        try:
            connection.close()
        except Exception:
            pass

    def close(self):
        while not self._available.empty():
            self._close_safely(self._available.get_nowait())

这段代码展示的是设计重点，而不是可直接复制到生产环境的驱动适配器。真正实现时还需要根据驱动特性处理事务回滚、连接数量统计、并发锁、创建失败和关闭竞态。

3. 为什么使用上下文管理

查询服务不应该手动记住“什么时候归还连接”，而应把借用和归还绑定到一个作用域：

with pool.acquire() as connection:
    rows = query_repository.fetch(connection, params)

无论查询成功、超时还是抛出异常，退出 with 块都会进入归还逻辑。对于写操作，还应在服务层明确提交或回滚；对于默认只读工具，可以在连接初始化时设置只读事务属性。

4. 不同数据源不要强行共用一个池

不同驱动的连接生命周期、线程安全模型和健康检查方式并不相同。因此更合理的是提供统一抽象，但保留各自实现：

PgPool       → PostgreSQL 驱动连接
MessagePool  → 消息系统客户端
DocumentPool → 文档或宽表数据源客户端

统一的是 acquire / release / close / health_check 等生命周期接口，不统一底层连接细节。这样既能让 Controller 调用方式一致，也不会为了抽象而抹平驱动差异。

5. 连接池必须配合任务调度

连接池的最大连接数和任务并发数要一起设计。假设查询任务最大并发为 3，那么单个数据源的连接池不必盲目开到几十个。连接数过多会把压力转移到服务端，连接数过少则会让任务长时间排队。

因此需要记录几个可观测指标：

• 当前池大小和已借出数量；
• 等待连接的任务数；
• 获取连接耗时；
• 健康检查失败次数；
• 查询耗时和取消次数。

这些指标只记录数量、状态和耗时，不记录查询结果、密码或敏感连接信息。

五、几个值得沉淀的设计亮点

连接池只是其中一环。回看整个工具的设计，我认为真正有迁移价值的亮点主要集中在“如何控制变化、如何保证界面响应、如何让错误可追踪”这三个问题上。

1. 用统一任务管理器替代散落的线程

早期桌面工具经常在每个按钮的槽函数里直接创建线程。这样做的问题是：线程没有统一的生命周期，窗口关闭时不知道哪些任务还在运行，异常和取消也各自处理。

统一任务管理器可以把任务当成应用资源管理：

class JobManager:
    def submit(self, job):
        """提交任务，并统一管理并发、进度、取消和完成回调。"""
        self._queue.put(job)

    def cancel(self, job_id):
        job = self._jobs.get(job_id)
        if job:
            job.request_cancel()

    def shutdown(self):
        for job in self._jobs.values():
            job.request_cancel()
        self._wait_for_all()

关键点不是这个类有多少方法，而是所有耗时操作都遵守同一个约束：

UI 只提交任务
Worker 只处理任务
Signal 只传递结果
UI 只在主线程更新控件

任务取消使用协作式方式。Worker 在读取、分页和批处理之间检查取消状态，资源释放放在 finally 中。这样比直接强杀线程更容易保证连接、游标、消费者和文件句柄处于可控状态。

2. 用“攒批 + 定时刷新”解决大结果集渲染

把查询结果每行发送给 UI，看起来实时，但信号频率过高时会让主线程花费大量时间处理事件。一次性把全部结果交给 UI，又会造成长时间无响应。

更实用的折中是：后台线程按固定数量攒批，或者按短时间窗口刷新：

class BatchEmitter:
    def __init__(self, emit, batch_size=200):
        self._emit = emit
        self._batch_size = batch_size
        self._buffer = []

    def append(self, row):
        self._buffer.append(row)
        if len(self._buffer) >= self._batch_size:
            self.flush()

    def flush(self):
        if self._buffer:
            self._emit(self._buffer)
            self._buffer = []

实际项目中还应配合定时器，避免低流量时最后一批迟迟不显示。这个设计同时解决了三个问题：用户能较早看到结果、信号数量可控、UI 有机会处理重绘和交互事件。

3. Model/View 让表格从“控件堆数据”变成“视图读模型”

大数据表格不适合逐个创建单元格控件。更合理的方式是：

原始数据模型 → 过滤/排序代理模型 → QTableView

模型保存行列数据，视图只在可见区域绘制。详情面板通过当前行索引读取原始数据，长文本不直接塞进表格单元格。

这类设计的价值在于，排序、筛选和详情查看都有明确的数据入口；未来替换表格外观时，也不需要重写查询服务。

4. 注册表比不断追加条件分支更适合扩展

当数据格式增加时，最容易出现一个几百行的函数：

if kind == "A":
    ...
elif kind == "B":
    ...
elif kind == "C":
    ...

注册表方式把“如何找到处理器”和“处理器如何工作”分离：

_DECODERS = {}


def register(kind):
    def decorator(decoder_cls):
        _DECODERS[kind] = decoder_cls
        return decoder_cls

    return decorator


@register("structured-message")
class StructuredMessageDecoder:
    def decode(self, raw_bytes):
        return {"kind": "structured", "value": parse_safely(raw_bytes)}


def decode(kind, raw_bytes):
    decoder_cls = _DECODERS.get(kind, FallbackDecoder)
    return decoder_cls().decode(raw_bytes)

新增格式时只增加一个解析器和配置，不修改原有分支。解析失败也不应直接吞掉异常，而应返回“已降级”的结果，同时记录可定位的错误原因。

5. 只读默认和参数化是查询工具的底线

本地工具往往拥有较强的查询能力，因此安全策略必须放在服务层，而不是只写在 UI 提示里。

一个通用的只读校验可以先做粗粒度拦截，再交给数据库权限做最终控制：

READ_ONLY_PREFIXES = ("select", "with", "show", "explain")
BLOCKED_WORDS = {"drop", "truncate", "delete", "update", "alter"}


def validate_read_only(sql):
    normalized = " ".join(sql.lower().split())
    if not normalized.startswith(READ_ONLY_PREFIXES):
        raise ValueError("默认模式只允许只读查询")
    if any(word in normalized.split() for word in BLOCKED_WORDS):
        raise ValueError("查询包含默认禁止的操作")

这段逻辑不能替代数据库权限，也不能用简单字符串判断覆盖所有 SQL 语法，但它能形成第一道防线。更重要的是，查询参数、动态标识符和写入权限必须分别处理，不能把“参数化”误认为所有安全问题都已解决。

6. 配置迁移要考虑旧版本和失败回滚

配置文件不是一次性脚本，而是长期演进的数据。新增配置项时，应提供默认值；修改字段名时，应支持一次性迁移；迁移失败时，保留原文件并给出明确提示。

推荐的迁移流程是：

读取旧配置 → 校验结构 → 生成新配置 → 原子替换 → 记录迁移版本

敏感值迁移到系统安全存储时，不能只“复制后删除”。应该先确认新存储写入成功，再清理旧字段，并在日志中只记录迁移结果，不记录敏感内容。

7. 错误分类让用户提示和开发日志各司其职

把所有异常直接显示 repr(error)，用户很难理解；把所有异常都包装成“操作失败”，开发又无法定位。可以按责任划分：

UserError    → 输入不合法，给出修改建议
ServiceError → 外部依赖失败，提示重试或检查连接
Bug          → 记录堆栈，避免界面直接崩溃

用户看到的是可执行的提示，日志保留错误类型、阶段和耗时。错误处理的目标不是隐藏失败，而是让失败可理解、可恢复、可追踪。

8. 懒加载解决的不只是启动速度

大型桌面工具中的解析器、工作区和外部客户端不一定都需要在启动时加载。把它们改为按需创建，可以降低冷启动时间和常驻内存，也能缩小首次运行时的故障范围。

但懒加载必须配合缓存和释放策略：首次使用时初始化，重复使用时复用，应用退出时统一关闭。否则只是把启动阶段的问题推迟到第一次点击。

六、用工作区模型组织桌面应用

桌面工具很容易把所有功能都放在一个主窗口里，最后变成大量按钮和弹窗。测试助手采用“连接管理器 + 独立工作区”的信息架构：

• 主窗口负责管理连接对象；
• 打开一个连接后进入对应工作区；
• 一个工作区使用多个 Tab 承载不同操作；
• 工作区之间互不阻塞，可以并行处理；
• 不常用的 Tab 延迟创建，减少首次打开成本。

这种设计把“我连接到哪里”和“我正在做什么”分开了。它也让用户更容易理解当前操作属于哪个连接，降低误操作风险。

结果展示采用 Model/View 思路，而不是把大量数据逐个塞入界面控件。数据模型负责保存和筛选，视图负责展示，详情面板负责查看当前选中项。这样可以支持更大的结果集，也能减少界面刷新次数。

七、让耗时操作不阻塞 UI

桌面应用的核心体验不是“功能很多”，而是点击之后界面仍然有响应。

测试助手将查询、消息读取、解码、导出和文件操作放到后台任务中，界面线程只负责：

• 发起任务；
• 接收批量结果；
• 更新进度条和状态栏；
• 响应取消请求；
• 在任务结束后刷新视图。

任务生命周期

一个任务至少应有以下状态：

queued → running → succeeded
                 ├→ failed
                 └→ cancelled

任务管理器负责统一处理：

• 并发上限；
• 排队；
• 任务标识；
• 进度回调；
• 优雅取消；
• 应用退出时的统一收尾。

取消任务时，应优先使用协作式取消：发送中断请求，让任务在安全检查点退出，并释放连接、游标、消费者和文件句柄。强制终止线程容易留下半写入文件、未释放连接或不一致状态。

分批返回结果

查询结果不必等全部完成后再一次性显示。服务层可以每积累一批数据就通知界面刷新一次：

读取一批 → 校验取消状态 → 发送一批 → 更新进度 → 继续读取

这样用户能尽早看到结果，内存占用也更可控。批大小应通过配置调整，而不是写死在界面代码里。

八、设计可扩展的数据解析入口

当工具需要处理多种结构化数据时，最容易出现的是大量条件分支：根据主题名、后缀或类型不断追加 if/elif。

更可维护的方式是建立注册表和统一解码接口：

输入：数据类型、原始字节、解析选项
输出：统一的数据对象，或明确的解析错误

新格式通过注册新的解析器接入，而不是修改一个越来越长的旧函数。注册表可以根据类型选择解析器，解析器内部只处理自己的格式。

同时保留合理的降级路径，例如：

专用解析 → 通用 JSON → 文本 → 十六进制展示

降级不是掩盖错误，而是保证用户仍然可以查看原始信息，并通过日志知道具体在哪一步无法解析。

这里不记录任何业务协议、字段定义或二进制文件内容。对外可公开的只是“如何设计解析扩展点”这一软件工程方法。

九、配置、日志和安全边界

配置分层

配置可以按以下优先级读取：

程序默认值 < 用户配置 < 环境变量

连接地址、超时、分页大小、界面偏好等非敏感配置可以保存到配置文件。密码、令牌和 AI 密钥不应写入普通 JSON，也不应出现在日志中，而应使用操作系统提供的安全存储能力。

日志分级

日志要服务于定位问题，而不是把所有内容都写下来。可以按以下方式区分：

• DEBUG：开发调试细节；
• INFO：任务开始、结束和耗时；
• WARNING：可恢复异常和降级行为；
• ERROR：影响当前功能的失败；
• CRITICAL：未捕获的严重异常。

日志还应主动脱敏：连接信息、用户输入、返回数据和异常文本都不能未经检查直接写入日志。记录“发生了什么”和“耗时多久”通常比记录完整数据更安全。

查询安全

自由查询能力必须设置边界：

• 默认使用只读模式；
• 查询参数使用参数化方式；
• 动态表名和字段名经过白名单校验；
• 危险操作需要额外确认；
• 导出和复制操作明确提示数据范围。

十、测试策略：验证行为，而不是验证文件存在

测试助手的测试分为三层：

单元测试

验证纯函数、参数校验、错误分类、配置解析、脱敏逻辑和解析器。单元测试应快速、稳定、可重复。

集成测试

验证服务与真实依赖之间的协作，例如连接、分页、超时、取消和资源释放。涉及外部依赖时，测试环境应使用独立的演示数据，不使用真实业务数据。

UI 测试

验证用户真正关心的行为：

• 能否创建和打开连接；
• 查询过程中界面是否保持响应；
• 取消后是否恢复可操作状态；
• 空结果和错误结果是否有清晰提示；
• 大结果集是否能滚动和筛选；
• 主题切换和窗口关闭是否正常。

每次改造前先记录基线，例如启动时间、首行结果时间、万行渲染耗时和内存占用。没有基线，就很难判断所谓“优化”是否真的有效。

十一、AI 参与开发的流程规范

AI 可以提高实现速度，但不能替代需求判断、安全审查和测试验收。测试助手的 AI 协作遵循以下流程。

1. 先给边界，再给任务

每次只让 AI 处理一个主题，例如“优化结果表格渲染”或“补充配置校验测试”，不要在一次任务里同时重构 UI、替换数据库驱动和调整发布流程。

任务描述应包含：

• 背景和目标；
• 允许修改的目录；
• 不允许触碰的敏感内容；
• 验收条件；
• 必须执行的测试命令。

2. AI 只接触最小必要上下文

Prompt 中不放密码、令牌、连接串、内部地址、业务名称、业务字段、协议文件和真实数据。需要分析代码时，只提供完成当前任务所需的最小片段，并优先使用脱敏后的示例。

3. AI 先分析再修改

执行顺序应当是：

理解需求 → 检查调用链 → 提出最小方案 → 修改一个主题 → 自测 → 复核 diff

AI 不应因为“顺手优化”而删除、移动或重命名无关文件，也不应把注释当成问题修复的替代品。

4. AI 生成代码必须经过工程门禁

至少执行：

• 格式化和静态检查；
• 单元测试；
• 相关集成测试；
• 关键 UI 流程验证；
• 敏感信息扫描；
• 构建和打包验证。

AI 的输出只能作为候选实现，最终是否合入由人根据需求、风险和测试结果判断。

5. 让 AI 参与文档沉淀

每项重要改动都应记录：为什么改、改了什么、如何验证、有什么已知限制。这样下次 AI 继续工作时，可以基于项目事实，而不是重新猜测历史背景。

十二、从工具开发中得到的经验

经验一：架构不是为了复杂，而是为了控制变化

分层、注册表和任务管理器只有在确实存在变化和复用时才有价值。架构设计的目标不是增加文件数量，而是把变化隔离在合适的位置。

经验二：性能问题通常来自数据流和线程边界

界面卡顿不一定是控件本身的问题，可能是查询、解码、格式化、日志或文件操作跑在了主线程。排查性能时应先画出完整数据流，再测量每个阶段的耗时。

经验三：安全设计应当默认发生

密码不落普通文件、日志主动脱敏、查询默认只读、外部输入经过校验，这些规则不能依赖开发者每次记得执行，而应当体现在统一的基础设施和服务接口中。

经验四：AI 越强，边界越重要

AI 能快速生成代码，也能快速放大错误。明确上下文边界、敏感信息边界、修改范围和验收标准，才能让 AI 真正成为开发协作者，而不是不可控的自动修改器。

结语

测试助手的开发过程，本质上是一次从“功能可以运行”走向“软件可以长期维护”的练习。真正值得沉淀的不是某个业务接口或某段内部实现，而是问题拆解、分层设计、异步任务、可扩展解析、测试验证、安全边界和 AI 协作流程。

这些方法不依赖特定行业，也不依赖某个业务系统。只要软件需要连接外部资源、处理数据、响应用户操作，并且还要持续迭代，就值得在设计阶段认真考虑这些问题。