Qt登录界面开发实践：状态机、SQLite与密码哈希的完整演进

聊一个很多 Qt 新手都会卡住的问题：登录界面。我最近把一个练手项目从第一版一直推到 Demo4，前面几个版本分别解决了窗口布局、信号槽、输入校验，到第四版我才真正意识到，登录界面的复杂度不在控件拼装，而在于交互状态怎么切、数据往哪里存、窗口之间怎么交接。这篇文章把 Demo4 的实现思路和踩坑过程完整记下来，给正在从“能跑”走向“能用”的 Qt 初学者做个参考。

1. 前三版 Demo 的演进逻辑：从摆控件到想清楚状态

1.1 Demo1 到 Demo3 各是什么，各自的极限在哪

Demo1 基本就是“画控件”：一个 QWidget，套一个 QVBoxLayout，上面两个 QLineEdit，下面一个 QPushButton，按钮点击后拿 qDebug 把输入内容打印出来。这个阶段练的是布局管理，搞清楚 setLayout、addWidget、间距和边距大概是怎么回事。做完之后你会觉得“哦，界面能出来了”，但代码里没有任何业务逻辑，按钮纯粹是个摆设。

Demo2 开始接信号槽。QPushButton::clicked 连一个 lambda，lambda 里读两个输入框的 text()，然后做最简单的处理——比如拼接成字符串打印出来。这个版本的关键收获是弄明白信号和槽的触发链路，也第一次感受到“界面和逻辑该分开”这个念头。代价是逻辑全堆在 lambda 里，如果再加一个“注册账号”按钮，lambda 就会迅速失控。

Demo3 开始做输入校验：账号空了弹一个 QMessageBox，密码空了再弹一个，账号密码都填了才继续。很多人的登录界面做到这里就停了，觉得“功能都有了”。但 Demo3 的问题非常明显：校验逻辑直接写在按钮槽函数里，提示用模态弹窗，用户每错一次都得手动点“确定”；重复点击按钮没有任何保护；回车键完全没处理；密码在代码里用字符串直接比对。这些隐患在 Demo3 这个规模下还能忍，但只要你想加一个真实数据库或网络请求，整个结构会立刻散架。

1.2 Demo4 的调整目标：把“能跑”变成“能用”

Demo4 我没有推倒重来，而是在前三版搭好的骨架上做结构性调整，目标很明确：

• 交互层面：登录按钮要有明确的状态切换，登录过程中不能重复点击，错误提示不能靠弹窗打断用户。
• 数据层面：记住账号这类偏好数据用本地配置保存，用户账号和密码哈希进入 SQLite，不再写死在代码里。
• 窗口层面：登录成功后要能自然切到主界面，退出登录后还能回到登录窗口，整个流程不会丢失状态。
• 体验层面：焦点顺序、Tab 键、回车键、密码可见性切换、错误边框反馈，这些细节决定了界面到底“像不像样”。

这一章写演进过程，是想让大家明白：登录界面的难点从来不是把几个控件摆上去，而是从“界面能出来”到“交互能闭环”之间的那段路。Demo4 就是用来补这段路的。

2. 登录按钮不是“用来点的”，它是一台小状态机

2.1 把按钮状态拆开，调试会轻松很多

很多初学者的登录按钮只有一种状态：能点。于是所有逻辑都堆在 clicked 槽里，一个 if 接着一个 if。Demo4 把登录按钮当成状态机来处理，状态拆成四个：

拆开之后，槽函数里就不需要再关心“按钮现在能不能按”，因为按钮的可用性在状态切换时就已经决定好了。这个思路对后续扩展也友好：如果以后登录要接网络接口，LoggingIn 状态可以挂一个转圈动画，Failed 状态可以记录失败次数，完全不用动其他代码。

2.2 textChanged 驱动按钮可用性，而不是等点击才判断

Demo4 里两个输入框的 textChanged 信号都连到一个 updateLoginButtonState() 方法：

void LoginWidget::updateLoginButtonState() { bool hasAccount = !m_accountEdit->text().trimmed().isEmpty(); bool hasPassword = !m_passwordEdit->text().isEmpty(); m_loginBtn->setEnabled(hasAccount && hasPassword); }

这里有一个细节很多人会忽略：账号要 trim 之后判断，密码不能 trim。原因是账号的前后空格通常是用户误输入，应该裁掉；但密码可能真的有空格，trim 会把合法密码给改了。密码框用 Password 回显模式时，末尾空格本来就看不见，一旦用户设置了带空格的密码，程序却把空格去掉再校验，那永远登不上。

2.3 防重复提交：m_loggingIn 和模拟耗时

点击登录后，第一件事不是校验，而是设置一个登录中标志位：

void LoginWidget::onLoginClicked() { if (m_loggingIn) { return; } QString account = m_accountEdit->text().trimmed(); QString password = m_passwordEdit->text(); if (account.isEmpty()) { setTip("请输入账号"); m_accountEdit->setFocus(); return; } if (password.isEmpty()) { setTip("请输入密码"); m_passwordEdit->setFocus(); return; } m_loggingIn = true; m_loginBtn->setEnabled(false); setTip("登录中..."); QPointer<LoginWidget> guard(this); QTimer::singleShot(600, this, [guard, account, password]() { if (!guard) { return; } guard->handleLoginResult(account, password); }); }

这个实现里用了 600ms 的 QTimer 来模拟异步校验，真实项目里替换成网络请求或线程即可。关键点是 m_loggingIn 标志位：它保证在登录结果返回前，用户点多少次按钮都不会重复触发请求。另外，lambda 捕获的是 QPointer 而不是裸 this，防止登录窗口在结果返回前被关闭，导致回调里访问悬空指针。

handleLoginResult 内部根据校验结果决定进入成功流程还是 Failed 状态。失败时把 m_loggingIn 恢复成 false，按钮重新启用，提示区显示“账号或密码错误”。

2.4 错误反馈用固定提示区，不要用 QMessageBox

Demo3 里每次校验失败都弹 QMessageBox，Demo4 改成了窗口底部固定一行 QLabel，叫 tipLabel，setWordWrap(true)。错误时文字变红，登录中时文字变灰。原因很简单：模态弹窗会打断用户输入节奏，连续输错几次，用户要反复去点“确定”，手感非常差；而固定提示区能让用户一眼看到错误原因，同时继续保持键盘输入焦点。

这一章的心得是：按钮状态和提示反馈是登录界面交互的骨架，把它们单独理清楚，后面接数据库接网络都顺。

3. 数据落地：QSettings 管偏好，SQLite 管用户

3.1 先分清楚哪类数据放在哪

登录界面涉及的数据可以分成两类：一类是“记住账号”这种本地偏好，一类是用户账号和密码哈希这种业务数据。Demo4 用了两种存储方案，分工如下：

这里需要强调一个观念：不要把配置和业务数据混在一个文件里。配置你用 QSettings 读出来就是 QVariant，非常轻；用户表你用 SQLite 建表做唯一约束，查起来也干净。混在一起会两边都别扭。

3.2 数据库路径和 QSettings 的路径坑

Demo3 之前我一直把数据文件放在可执行文件同目录，后来发现很蠢：程序装到系统目录或者 macOS 的 .app 包里，当前目录根本不可写。正确做法是使用 QStandardPaths：

QString dataDir = QStandardPaths::writableLocation(QStandardPaths::AppDataLocation); QDir().mkpath(dataDir); QString iniPath = dataDir + "/login_config.ini"; QString dbPath = dataDir + "/login_demo.db";

不同平台上这个目录不一样，Windows 是 AppData 下的 Roaming 目录，Linux 是 ~/.local/share 下的应用目录，macOS 是 Application Support。不用自己拼路径，QStandardPaths 会帮你定位。注意 mkpath 必须调用，否则目录不存在时后面写文件会失败。

QSettings 本身也有几个使用习惯可以分享。Demo4 里我显式指定了 INI 格式和用户级作用域：

QSettings settings(QSettings::IniFormat, QSettings::UserScope, qApp->applicationName());

显式指定格式，是为了避免不同平台上默认后端不一致。比如 Windows 默认可能是注册表，Linux 默认是 INI，同一套代码在不同平台行为不统一，调试时就非常难受。写入时中文建议转成 UTF-8：

settings.setValue("login/rememberAccount", remember); if (remember) { settings.setValue("login/account", account.toUtf8()); } else { settings.remove("login/account"); } settings.sync();

读回来：

bool remember = settings.value("login/rememberAccount", false).toBool(); QString account = settings.value("login/account").toString();

sync() 是为了让配置立刻落盘，不然可能在程序退出时才写文件。还有一个小坑：如果直接存路径字符串，INI 里的反斜杠会被转义，Windows 路径尤其明显，建议统一用 QDir::toNativeSeparators 或者尽量存正斜杠。

这里要特别说明一个取舍：Demo4 只实现“记住账号”，不实现“记住密码”。原因是 Qt 本身没有跨平台的系统钥匙串封装，如果把密码写进 INI，哪怕再做一层简单加密，也只是把秘密换了个位置藏，并不算真正的安全。真正的“记住密码”应该落到操作系统自带的 Keychain、Credential Vault 这类安全存储里，那是另一个独立话题。Demo 阶段明确不碰，避免给读者留下“加密一下就安全了”的错误印象。

3.3 用户表建模和注册流程

用户表结构设计得比较简单：

CREATE TABLE IF NOT EXISTS users ( id INTEGER PRIMARY KEY AUTOINCREMENT, account TEXT NOT NULL UNIQUE, salt BLOB NOT NULL, pwd_hash BLOB NOT NULL, created_at TEXT NOT NULL );

account 字段加 UNIQUE 约束，数据库层面就能保证账号不重复，注册时靠约束兜底，不用先查一遍再插。salt 和 pwd_hash 用 BLOB 存原始字节，比转成十六进制字符串省一半空间，读出来直接用 QByteArray 接。created_at 用 TEXT 存 ISO 格式时间字符串，直观且 SQLite 的日期函数也能处理。

Qt 里操作 SQLite 需要先初始化连接。我习惯给数据库连接起单独的名字，避免在多个窗口共用一个全局连接时混乱：

bool UserDb::init(const QString& dbPath) { QSqlDatabase db = QSqlDatabase::contains(connectionName) ? QSqlDatabase::database(connectionName) : QSqlDatabase::addDatabase("QSQLITE", connectionName); db.setDatabaseName(dbPath); if (!db.open()) { qWarning() << "open db error:" << db.lastError().text(); return false; } QSqlQuery query(db); return query.exec("CREATE TABLE IF NOT EXISTS users (... )"); }

注册用户的插入操作必须用 prepare 加 bindValue，而不是拼字符串。这个习惯必须在一开始就养成：

bool UserDb::registerUser(const QString& account, const QString& password) { QByteArray salt = PasswordHash::makeSalt(); QByteArray hash = PasswordHash::pbkdf2(password, salt); QSqlQuery query(m_db); query.prepare( "INSERT INTO users(account, salt, pwd_hash, created_at) " "VALUES(:account, :salt, :hash, :created)"); query.bindValue(":account", account); query.bindValue(":salt", salt); query.bindValue(":hash", hash); query.bindValue(":created", QDateTime::currentDateTime().toString(Qt::ISODate)); return query.exec(); }

这一章的结论是：QSettings 和 SQLite 各管一摊，路径统一走 QStandardPaths，SQL 全部参数绑定，数据层的结构基本就稳定了。

4. 密码不直接比字符串：哈希方案的选择

4.1 为什么“登录时用数据库里的密码比对”是错的

很多教程会把密码以明文或者简单编码形式存进数据库，登录时把输入内容和数据库字段直接 equals。这样做的后果是：任何能读到数据库文件的人，等于直接拿到了所有用户的密码。Demo4 虽然只是个练手项目，但处理用户数据的习惯应该从一开始就接近真实工程。密码在数据库里保存的应该是哈希值，而不是可读文本。

4.2 哈希不等于是 SHA-256

谈到密码哈希，绕不开的一个错误示范是 QCryptographicHash 配 Sha256。这个组合做文件校验没问题，做口令存储不合适。原因在于 SHA-256 太快了，暴力跑字典的成本很低。口令哈希需要用专门设计的慢函数，比如 PBKDF2、bcrypt、Argon2。

Demo4 选 PBKDF2，原因很现实：可以在现有 Qt 工程里用少数代码接起来，概念上又比直接 SHA-256 正确。下面是一个简单的封装：

#include <openssl/evp.h> QByteArray PasswordHash::makeSalt() { QByteArray salt(16, Qt::Uninitialized); QRandomGenerator::system()->fillRange( reinterpret_cast<quint32*>(salt.data()), salt.size() / 4); return salt; } QByteArray PasswordHash::pbkdf2(const QString& password, const QByteArray& salt, int iterations = 100000) { QByteArray out(32, Qt::Uninitialized); QByteArray pwd = password.toUtf8(); int ok = PKCS5_PBKDF2_HMAC( pwd.constData(), pwd.size(), reinterpret_cast<const unsigned char*>(salt.constData()), salt.size(), iterations, EVP_sha256(), out.size(), reinterpret_cast<unsigned char*>(out.data())); return ok ? out : QByteArray(); }

这里要注意，password 的 toString 和 toUtf8 会在内存里留下临时副本，真实工程里可以考虑用 QPasswordDigestor 或者更细的缓冲清理方案，Demo 阶段先用最直观的写法。

4.3 盐的随机性和恒定时间比较

盐用 QRandomGenerator::system() 生成 16 字节，每个用户单独生成。两个用户即使密码一样，因为盐不同，最终的哈希也完全不同。校验密码时把盐从数据库取出来，重新计算一次 PBKDF2，再和库里存的哈希比较。

比较哈希时不要直接用 QByteArray::operator==，这个函数遇到第一个不同字节就返回，时间上会泄露一些信息。Demo 里影响不大，但是口令校验属于高敏感操作，最好用固定循环比较：

bool PasswordHash::verify(const QString& password, const QByteArray& salt, const QByteArray& expected) { QByteArray actual = pbkdf2(password, salt); if (actual.size() != expected.size()) { return false; } unsigned char diff = 0; for (int i = 0; i < actual.size(); ++i) { diff |= static_cast<unsigned char>( actual.at(i) ^ expected.at(i)); } return diff == 0; }

这一章的核心观点就一句话：口令存储不要走“字符串直接比对”的捷径，用带盐的 PBKDF2 做哈希，校验时用恒定时间比较，成本很低，但安全习惯的价值很高。

5. 登录成功之后：窗口交接和登录态传递

5.1 不要让登录窗口自生自灭

很多新手实现登录成功后，会在登录窗口里直接 new 一个 MainWindow，然后把自己的窗口 hide 或 close。但如果登录窗口用了 deleteOnClose，那它会在 close 时把自己销毁，后续“退出登录返回登录页”就完全没有可用对象了。

Demo4 的做法是：main 函数里只创建 LoginWidget，登录窗口本身不设置 deleteOnClose，关闭只是隐藏。登录成功的信号发出后，由 LoginWidget 自己创建主窗口：

int main(int argc, char* argv[]) { QApplication a(argc, argv); QApplication::setOrganizationName("DemoOrg"); QApplication::setApplicationName("LoginDemo"); LoginWidget loginWidget; loginWidget.show(); return a.exec(); }

不要用 QDialog::exec() 来阻塞等待登录结果，因为 exec() 会进入嵌套事件循环，遇到异步网络请求和窗口切换会非常别扭。普通 QWidget + 信号槽的方式才符合 Qt 的事件驱动模型。

5.2 登录态怎么传给主界面

登录成功后，账号和时间等数据不能散落在各个控件里。定义一个轻量的结构体：

struct UserInfo { QString account; QDateTime loginAt; };

MainWindow 构造函数直接接收 UserInfo，主窗口只从外部拿数据，不在内部二次查库。这样主界面的职责就纯粹了：负责展示业务界面，不负责登录逻辑。

5.3 退出登录和窗口销毁的坑

退出登录的流程是这样：主窗口发出 logoutRequested 信号，登录窗口接收后清理输入框状态，重新 show()，同时把主窗口对象排进删除队列：

void LoginWidget::onLoginSucceeded(const UserInfo& info) { if (m_mainWindow) { m_mainWindow->deleteLater(); } m_mainWindow = new MainWindow(info); m_mainWindow->show(); close(); connect(m_mainWindow, &MainWindow::logoutRequested, this, [this]() { resetLoginForm(); show(); }); }

这里可以看到，登录窗口 close() 之后对象并没有销毁，只是隐藏了，所以退出登录后还能 show() 回来。主窗口用了 deleteLater 而不是直接 delete，避免在信号处理过程中销毁还在执行槽的对象。

踩过的一个坑是：如果登录窗口的 closeEvent 里有 deleteLater 或者设置了 WA_DeleteOnClose，那么退出登录时登录窗口自己已经没了，再调 show() 就是空指针操作。Demo4 明确不用 deleteOnClose，这也是很多 Qt 窗口切换示例没讲清楚的地方。

5.4 登录请求未结束时关闭窗口

用户点击登录后，如果校验还没返回就关闭窗口，异步回调里还在操作界面控件，这属于典型的悬空访问。QTimer 回调里必须用 QPointer 保护，同时 closeEvent 里要取消挂起的请求：

void LoginWidget::closeEvent(QCloseEvent* event) { m_pendingLogin = false; QWidget::closeEvent(event); }

这里的 m_pendingLogin 是登录请求的取消防护。如果请求是在线程里跑，则要等线程退出再关闭窗口。返回值允许异步，但窗口生命周期必须同步控制好。

6. 让登录界面“像样”的细节：焦点、眼睛和错误反馈

6.1 Tab 顺序和回车键

键盘操作是登录界面最容易忽略的部分。打开窗口时默认焦点应该落在账号输入框，Tab 顺序应该是账号到密码再到登录按钮。两个输入框的 returnPressed 都连到同一个登录槽，用户在密码框里按回车就能直接触发登录，不用摸鼠标点按钮。

setTabOrder(m_accountEdit, m_passwordEdit); setTabOrder(m_passwordEdit, m_loginBtn); m_accountEdit->setFocus(); connect(m_accountEdit, &QLineEdit::returnPressed, this, &LoginWidget::onLoginClicked); connect(m_passwordEdit, &QLineEdit::returnPressed, this, &LoginWidget::onLoginClicked);

Tab 到登录按钮后按空格也能触发 clicked，这是按钮控件的默认行为，不用额外处理。

6.2 密码可见性切换

密码框默认用 QLineEdit::Password 回显小圆点，用户输错几次之后会怀疑自己是不是按到了大写锁定，这时候最好能切到明文看一眼。QLineEdit::addAction 可以放一个眼睛按钮在输入框右侧：

m_visibilityAction = m_passwordEdit->addAction( QIcon(eyeOffPath), QLineEdit::TrailingPosition); connect(m_visibilityAction, &QAction::triggered, this, [this]() { bool hidden = m_passwordEdit->echoMode() == QLineEdit::Password; m_passwordEdit->setEchoMode(hidden ? QLineEdit::Normal : QLineEdit::Password); m_visibilityAction->setIcon( QIcon(hidden ? eyeOnPath : eyeOffPath)); });

切换到明文状态后，密码会直接显示在屏幕上，截图、录屏、远程桌面都可能看到。真实产品里通常会在切换后几秒自动切回密码模式，以及切换图标表示当前状态。这些细节 Demo4 都做了，成本不高，但体验会有明显提升。

CapsLock 提示这里多说一句：Windows 上可以通过系统接口拿到大写锁定状态，但跨平台没有统一 API，Demo4 只在控制台打印，没做成品提示。这个功能适合有平台特定需求时再做。

6.3 校验失败的视觉反馈与窗口缩放兜底

账号或密码错误时，除了底部提示区变红，输入框边框最好也同步反馈。Qt 里可以给控件加动态属性，再通过 QSS 控制样式：

QLineEdit { border: 1px solid #d0d0d0; border-radius: 4px; padding: 6px 8px; } QLineEdit[inputError="true"] { border: 1px solid #e74c3c; }

设置属性之后必须刷新样式，否则不会立刻变色：

void LoginWidget::setInputError(QLineEdit* edit, bool error) { edit->setProperty("inputError", error); edit->style()->unpolish(edit); edit->style()->polish(edit); }

这不是 Qt 的 bug，是样式系统为了性能做了缓存。动态属性变化不会自动触发重绘，必须手动 unpolish/polish 一下。错误状态保持 1 到 2 秒后恢复，同时用户继续输入时也要清掉错误标记。

窗口缩放兜底也值得一提：登录窗口要给主窗口设置一个合理的最小尺寸，比如 setMinimumSize(420, 340)，避免用户拖小窗口后控件挤成一团。布局边距建议用 24 左右，上下左右一致，spacing 保持 12，整体观感比默认值轻盈不少。如果窗口里有 Logo 或者横幅，用固定高度并 setScaledContents，避免布局拉伸后比例失衡。

做到 Demo4 我对登录界面的理解变了不少。最开始以为它在考布局，后来发现是信号槽，再后来发现真正的篇幅全花在状态管理、数据存储和窗口交接上。如果你也在练这个题目，别停在 Demo3 的“能弹窗”，把上面这些维度逐个补齐，代码量可能会翻一倍，但结构反而更清楚。下一版 Demo5 我计划把离线用户和真实 HTTP 登录接口接起来，到时候再回来补一篇接口联调的经验。