Notes — 03 Posts

踩过的坑,
写下来就不用踩第二次。

三篇都是真事,代码是从项目里直接抠出来的,不是拼凑的示例。 写得不够专业,但每一条都是自己撞出来的。

2026.04.12

五种状态,怎么变成一张能追责的工单

从宿管那句「报了呀」讲起:五个状态、四条规则,以及为什么判断必须写在服务端。

设计
2026.03.02

用原生 Node http 写后端,我踩的 5 个坑

body 为什么要拼接、并发写文件怎么互相覆盖、错误码该怎么设计。

后端
2026.01.18

把 Flask 服务放到局域网上,手机却打不开

127.0.0.1 与 0.0.0.0 的区别、防火墙入站规则、同网段,以及接口地址该怎么集中管。

联调

2026.04.12 · 设计 · 约 7 分钟

五种状态,怎么变成一张能追责的工单

做寝修宝之前,我以为报修系统的核心是那张提交表单。跟宿管聊完才发现不是—— 核心是「这张单子现在归谁、下一步谁能动」。表单只是一次输入,状态才是骨架。 这篇讲我怎么把一堆口头规矩收敛成五个状态、四条规则,以及为什么判断必须写在服务端。

单子是怎么丢的

我宿舍水龙头漏了两周。问宿管,她说「报了呀,可能在排队」;问维修师傅,他说「没看到这个单子」。 两句话都不假,但单子在中间消失了。第二天我蹲了半天值班室,记下四件事:

  • 报修走微信群,消息几小时就被刷走,宿管靠翻聊天记录找
  • 宿管拿纸质本子登记,字迹和楼号经常对不上
  • 维修师傅一天来抄一次单子,当天报的基本修不上
  • 学生唯一能做的就是再问一遍

对应四个问题:信息不完整、责任不清晰、进度不透明、数据难统计。 前两个靠结构化表单能解决,后两个只能靠状态流转。

状态不是功能清单,是责任清单

一开始我想做成「谁都能改状态」,宿管立刻否了。她需要知道这单是不是经她派的, 师傅需要知道这单是不是派给自己的。所以每个状态真正回答的问题是: 现在轮到谁。

工单状态流转 / 5 states · 4 rulest_repair_order.status
     学生提交
        │
        ▼
  [ 0 待处理 ] ── 学生取消(仅此状态)──▶ [ 4 已取消 ] · 终态
        │
        │ 维修工接单 / 宿管指派
        ▼
  [ 1 处理中 ]
        │
        │ 填写处理备注并完工
        ▼
  [ 2 已完成 ]
        │
        │ 学生评分 + 文字评价
        ▼
  [ 3 已评价 ] · 终态

  旁路:催单不改变状态,只在 0 / 1 阶段累加 urge_count

状态用 TINYINT 存 0–4,不用字符串。省空间只是次要的, 主要是判断「是不是管理类角色」时可以直接写 role >= 1,不用维护一张枚举表。

四条规则

1. 正向流转,每一步换一个人

0→1 由维修工接单或宿管指派触发;1→2 必须填了处理备注才能完工; 2→3 只能由提交者本人评价。每一步都对应一个具体的人,不是「管理员随便改」。

2. 取消只有一条路

只有「待处理」能取消。师傅一旦接单、投入了工时,就不允许学生单方面终止。 这条不是我拍脑袋定的,是宿管提的:以前纸质本子上有学生上午报、中午自己修好了, 师傅白跑一趟。规则不是技术限制,是业务流程的翻译。

3. 终态冻结,但数据不删

已评价(3)和已取消(4)不再接受任何变更。为什么不用删除来做「结束」? 因为后面要算平均接单时长、返修率,都得靠这些记录。 所以终态只是冻结,对终态工单发任何变更请求,统一返回 400。

4. 催单是旁路,不是状态

这是我最初设计错的地方——我本来想加一个「已催单」状态。 后来发现不对:状态描述的是「这单走到哪一步」,催单描述的是「急不急」, 两件事不在一个维度上。硬塞进状态机的话,一个「处理中、且被催了三次」的单子该怎么表示?

所以催单只做一件事:urge_count += 1,不改状态。 它可以在待处理和处理中反复执行,师傅在列表里看到次数就知道轻重。 一个字段能表达的东西,不要再加一个状态。

最关键的一行判断

前端会按角色隐藏按钮,这只解决好不好用。真正拦人的地方在服务端—— 隐藏按钮拦不住任何人打开控制台直接构造请求。

app/blueprints/order.py — 接单Flask
# 维修工接单:状态 0 -> 1,记录处理人与接单时间
@order_bp.route('/start/<int:order_id>', methods=['POST'])
def start_order(order_id):
    order = db.session.get(RepairOrder, order_id)
    if order is None:
        return jsonify(code=404, msg='工单不存在', data=None)
    # 关键:不信任前端传来的状态,只认库里的 status
    if order.status != 0:
        return jsonify(code=400, msg='该工单已被接单或已取消', data=None)

    payload = request.get_json(silent=True) or {}
    order.status = 1
    order.handler_name = payload.get('handler_name') or '维修师傅'
    order.start_time = datetime.now()
    db.session.commit()
    return jsonify(code=200, msg='已接单', data=order.to_dict())

这段代码里没有任何一行信任客户端传来的 status。 前端说「这单还是待处理」不算数,从数据库读出来的才算。 对一张已完成的工单再调一次,返回的是 400,而不是把状态改回 1。

状态机不是画给答辩看的那张图,它是「谁能做什么」的唯一真相来源。 图会过时,代码里那行判断不会。

状态机的边界,是用例固定住的

25 条用例覆盖账号、报修、管理、统计、送水五个域。正常流程大多一次就过, 真正容易漏的是异常分支:空字段提交、超长描述、重复提交、 以学生身份请求别人的工单详情、对已完成工单重复接单。

这几条的价值不在「证明它能用」,而在「证明它不能乱用」。 接口写完之后我自己手动点,永远只会走正常路径; 只有把「不该成功的情况」也写成用例,状态机的边界才算真的固定下来。

学到了什么

以前我以为状态机是「文档里画一下」的东西。做完才明白, 它的价值在于把模糊的口头规则逼成可执行的判断—— 「师傅接单后学生不能取消」这种话,写在需求里没人会反对; 写成 if order.status != 0: return 400 之后,它才真的会发生。

完整的建表语句、22 个接口清单在 案例页; 想直接打接口的话, 实验室里有四个按钮。


2026.03.02 · Backend · 约 9 分钟

用原生 Node http 写后端,我踩的 5 个坑

这个作品集的后端——就是实验室里那个会返回 JSON 的接口——没用 Express, 是 Node 自带的 http 模块硬写的。踩了一堆坑,但也第一次真正明白框架在干什么。

坑 1:req.body 不存在

我照着教程写 const { name } = req.body,永远是 undefined, 以为是版本问题,折腾了一晚上。

真相:req 是一个 ReadableStream,请求体不会一次性给你, 而是分块(chunk)推送过来。要自己监听 data 累积、end 时才算收完。

第二个坑藏在里面:不能把 chunk 转成字符串再相加。 中文字符可能被切在两个 chunk 中间,拼接后就是乱码。必须先拼 Buffer, 最后统一 toString('utf8')。

正确的做法含大小限制
function readBody(req, limit = 32 * 1024) {
  return new Promise((resolve, reject) => {
    const chunks = [];
    let size = 0;

    req.on('data', (chunk) => {
      size += chunk.length;
      if (size > limit) {
        // 一定要 destroy,否则客户端还在传,内存继续涨
        req.destroy();
        return reject(Object.assign(new Error('too large'), { status: 413 }));
      }
      chunks.push(chunk);            // Buffer 数组
    });

    req.on('end', () => {
      resolve(Buffer.concat(chunks).toString('utf8'));   // 最后才转字符串
    });

    req.on('error', reject);
  });
}

顺便说,大小限制必须加。我第一版没加,有人传了个 200MB 的文件, 进程直接 OOM 被杀——那是第一次被真实用户搞挂服务器。

坑 2:并发写文件会互相覆盖

我用 fs.writeFile 存上传的图片。测试时单人操作没问题, 上线后两个人同时提交,其中一张图变成 0 字节。

原因:writeFile 不是原子操作,内部是「打开 → 截断 → 写入」。 两个请求交错时,后一个的截断会把前一个还没写完的内容清掉。

解法是写临时文件再 rename。 在同一文件系统内,rename 是原子操作——要么指向新文件,要么还是旧文件, 不存在「半个文件」的中间态。

原子写入node:fs/promises
const { writeFile, rename } = require('node:fs/promises');
const path = require('node:path');
const crypto = require('node:crypto');

async function atomicWrite(target, buf) {
  // 临时文件名加随机后缀,避免并发时撞名
  const tmp = path.join(
    path.dirname(target),
    '.tmp-' + crypto.randomBytes(6).toString('hex')
  );

  await writeFile(tmp, buf);
  await rename(tmp, target);   // 原子替换
}

坑 3:错误码全用 400,前端没法处理

我一开始所有失败都 res.writeHead(400)。前端拿到的信息只有「失败了」, 没法区分是「你填错了」还是「你没登录」还是「这单已经不能派了」。

后来统一成一套语义,前端写起来就清楚了:

  • 400 请求格式不对(JSON 解析失败)
  • 401 未登录 / session 过期 → 前端跳登录页
  • 403 登录了但没权限 → 提示「无权限」
  • 404 资源不存在
  • 409 状态冲突(给已完成的单派单)→ 提示刷新
  • 422 参数校验失败 → 带上字段级原因
  • 429 请求过频 → 前端显示倒计时

其中 422 最有价值,响应体里要能告诉前端具体哪个字段错了:

422 响应体字段级错误
{
  "error": "VALIDATION_FAILED",
  "fields": {
    "email": "格式不正确",
    "message": "至少 10 个字"
  }
}

前端拿到 fields 就能直接把红框标在对应输入框下面, 不用维护一份「错误文案映射表」。这一改动让表单体验好了非常多。

坑 4:事务没包住,状态和流水对不上

状态流转要做两件事:更新 tickets.status、往 ticket_status_log 插一条。我最初分开执行,有一次第二步报错, 结果状态变了但没留痕——「这单谁改的」彻底查不到。

必须放在一个事务里。而且要注意:MySQL 的 autocommit 默认开启, 每条 SQL 自成事务。想手动控制就得先 BEGIN, 并且用同一个连接对象执行所有语句——连接池里不同连接是不同的会话,事务会串。

事务写法mysql2/promise
const conn = await pool.getConnection();
try {
  await conn.beginTransaction();

  await conn.execute(
    'UPDATE tickets SET status = ?, assignee_id = ? WHERE id = ?',
    [to, assignee, id]
  );
  await conn.execute(
    'INSERT INTO ticket_status_log (ticket_id, from_status, to_status, actor_id) VALUES (?,?,?,?)',
    [id, from, to, user.id]
  );

  await conn.commit();
} catch (e) {
  await conn.rollback();
  throw e;
} finally {
  conn.release();   // 别忘了还回连接池,否则池子会被耗尽
}

坑 5:以为 0.0.0.0 和 127.0.0.1 是一回事

server.listen(3000) 默认绑定 0.0.0.0, 意思是「所有网卡都能访问」,包括公网。

我以为防火墙只开了 80,内网没关系。结果在日志里看到大量外部扫描请求—— 说明这个端口是通的。后来改成显式绑定 127.0.0.1, 只保留本机访问,外部彻底进不来。

只监听本机推荐
const server = http.createServer(handler);

// 不要写 server.listen(3000)
server.listen(3000, '127.0.0.1', () => {
  console.log('api on http://127.0.0.1:3000');
});

所以框架到底解决了什么

写完这些坑,我大概明白了 Express 这类框架的价值:它不是「帮你省代码」, 而是把容易做错的地方做对——body 解析、错误处理、路由匹配、 中间件顺序、安全头。这些东西自己写都能写出来,但每一处都要踩一遍才知道边界在哪。

现在让我选,项目会直接用框架。但我不后悔手写一遍——因为面试官问 「为什么 Express 要装 body-parser」的时候,我答得出来。


2026.01.18 · 联调 · 约 6 分钟

把 Flask 服务放到局域网上,手机却打不开

后端在自己电脑上 curl 得好好的,手机输同一串地址却一直转圈。 这不是代码问题,是三个「默认值」在拦你。

起因:我需要让手机连上

寝修宝是微信小程序,必须在手机上跑。前端编译出来容易, 难的是让手机访问到我电脑上的 Flask 服务 —— 这一步卡了我一个下午。

当时的现象是:电脑浏览器访问 http://127.0.0.1:8080/api/user/login 正常返回, 手机输入 http://192.168.1.7:8080/api/user/login 一直转圈,最后提示网络异常。

第一件:127.0.0.1 和 0.0.0.0 不是一回事

Flask 的 app.run() 默认只监听 127.0.0.1, 也就是「只接受本机发来的连接」。手机是从局域网进来的,属于外部连接,直接被丢掉。

run.py监听所有网卡
# 之前:只有本机能访问
app.run(port=8080)

# 之后:局域网内任何设备都能连
app.run(host='0.0.0.0', port=8080)

0.0.0.0 的意思是「绑定所有网卡」,包括 Wi-Fi 那一块。 很多人以为它是个地址,其实它是个通配符 —— 这也解释了为什么 curl 0.0.0.0:8080 有时也能通:系统会把它当成本机。

第二件:系统防火墙的入站规则

改完 host 还是不通。因为系统默认拦截未放行的入站连接, 而 8080 不在白名单里。第一次运行 Python 时如果点过「取消」, 那条规则就是「阻止」,之后不会再弹窗问你。

管理员终端放行 8080 入站
netsh advfirewall firewall add rule ^
  name="flask-dev-8080" dir=in action=allow ^
  protocol=TCP localport=8080

# 用完记得删掉
netsh advfirewall firewall delete rule name="flask-dev-8080"

也可以直接在「Windows Defender 防火墙 → 允许应用通过防火墙」里勾上 Python, 但命令行更快,而且换电脑时能复制粘贴。测完记得删掉这条规则 —— 开发端口不应该长期对局域网敞开。

第三件:手机和电脑得在同一个网段

这一步最容易被忽略。宿舍的校园网常开「AP 隔离」,同一个 Wi-Fi 下的设备互相看不见; 有些路由器还会把 2.4G 和 5G 分成两个子网。

判断方法很简单,在电脑上查自己的内网地址:

cmd找内网 IP
ipconfig

# 看无线网卡那段,找 IPv4 地址,例如 192.168.1.7
# 手机浏览器打开 http://192.168.1.7:8080/api/user/workers
# 能出 JSON 就说明通了

如果还是不通,把手机开热点、电脑连手机热点,两台设备就在同一网段了, 这是最快的验证方式。校园网不行不代表代码有问题。

顺手要改的:接口地址不能写死

连通之后马上会遇到下一个问题:接口地址写在每个页面里,从本机调试切到真机联调, 要改十几个文件,改漏一个就报网络错误。所以我把地址收进一个配置文件:

pages/utils/config.js一处改,全局生效
// 本机调试 / 真机联调 / 部署,切环境只改这一行
// export const BASE_URL = 'http://127.0.0.1:8080'
export const BASE_URL = 'http://192.168.1.7:8080'

这件事看起来很小,但它是我这个项目里收益最高的一个改动: 后面每次换网络环境,只需要改一行,再也不用全局搜索。

为什么最后没有上公网

老实说,寝修宝最终只跑在局域网里:后端是我电脑上的 Flask 内置服务器, 数据库是本机的 MySQL 8.0,测试是拿两部手机连着同一个 Wi-Fi 做的。 没上公网有三个现实原因:学校服务器申请要走流程、域名解析到国内 IP 需要备案、 而这个项目当时的定位是毕业设计,不是要长期运营的产品。

这是一个明确的局限,我把它写进了论文第 7 章的「不足与展望」。 如果要真上线,缺的是这几块:用 gunicorn + nginx 替掉 Flask 内置服务器、 图片从本地磁盘挪到对象存储、以及给接口加缓存。

联调卡住的时候,八成不是代码写错了,而是「我以为默认是这样」。 先确认监听地址、防火墙、网段这三件事,比读代码快得多。

学到了什么

这件事之后我养成了一个习惯:报错先分层,别先改代码。 网络层的错(连不上)和应用层的错(返回 500)看起来都是「没反应」, 但排查路径完全相反。先 ping、再 curl、最后才看日志, 顺序反了就要多花一倍时间。