可以换普通词、拆长句,但要保留发生条件、因果、结果和异常时的下一步。否则“这次响应没有新正文”会变成“网页没有内容”,“通知得到了成功响应”会变成“订单已经处理完”。句子更短了,判断却错了。
下面以 ChatGPT 网页版为例,把网页 304 响应和 Stripe 支付通知两段说明写给普通运营人员看。原文、错稿与改稿均为本教程编写的教学示例,技术含义依据官方资料,没有真实故障或模型实跑记录。
完整原文和一份提示,一起交给它
真实任务先取得维护者确认的说明。不要只交“解释一下304”这样的术语:模型缺少原文情境,就容易补出你并不需要的操作。
P1 网页304响应
在浏览器已有缓存副本并发送条件GET请求的情况下,
服务器依据请求中的If-None-Match与资源的ETag比较,
判断版本未变时可返回304。该响应不带新的正文,
浏览器沿用已有副本。
304不证明网站刚修改的内容已正确发布。
如果编辑预期的新内容仍未显示,应把页面地址、修改时间
和自己看到的页面交维护者,对照实际发布内容与请求、
响应中的版本校验信息检查。
P2 Stripe支付通知
Stripe的Webhook可能重复投递,事件到达顺序也不保证。
网站处理通知前要验证签名,确认通知来源;
记录已经处理的事件ID,避免同一事件重复执行业务动作。
不同事件ID有时也可能对应重复的业务通知,
还要结合data.object的ID、event.type和业务记录核对,
不能把同一订单的所有不同事件都当成重复丢掉。
HTTP 2xx只表示网站通知接收地址给了成功响应,
不能证明后续订单动作已经全部完成。
发现一笔业务有多条通知或订单结果不符时,
由维护者对照事件编号、业务对象、事件类型和处理日志排查。
普通编辑先记录现象,不反复手动重发通知。
P1 的 GET 是取网页内容的一种请求。ETag 可理解为资源的版本标记;浏览器用 If-None-Match 携带已有标记,请服务器比较版本是否变化。304 是服务器返回的状态码,即说明这次请求情况的编号。MDN 的 304 参考说明,相应条件请求得到 304 时没有响应正文,客户端沿用缓存副本。
P2 的 Webhook 是支付平台主动发给网站的通知。签名让程序检查来源;事件 ID 是事件编号,data.object 的 ID 标明涉及哪个业务对象,event.type 表示发生哪类事件。2xx 指 200 等以 2 开头的成功响应。Stripe 的官方说明区分了重复事件、到达顺序和业务处理。
在ChatGPT 网页新建对话,把两原文和以下提示一起粘贴:
请把P1、P2分别改成普通网站编辑能读懂的完整中文说明。
保留原文的条件、因果、结果和异常下一步,技术词首次短解释即可。
可以拆句和解释,不新增原文没有的技术操作,不把“可能”改成“必然”。
尤其分清304无新正文与网页能显示、通知成功响应与订单业务完成;保留P2两类重复的区别。
先给两个完整改稿,再指出原文中不能理解或有冲突的具体句子,缺信息不猜。
304:不发新正文,网页仍然可以显示
教学错稿是:“304说明网页没有内容。刷新一下,就能加载最新文章。”
它改了原文的对象:不带新正文说的是这次响应,不是网页不存在;“刷新就最新”也没有依据。完整改稿应把浏览器手里的副本说清楚:
浏览器可能已经保存了一份网页副本。再次访问时,它可以带着这份副本的版本信息,问服务器:“这份内容有没有变化?”服务器比较后认为版本未变,就可能返回304。
304这次不带新的网页正文,浏览器继续使用已有副本,所以你仍然可以看到网页。缓存就是先保存一份内容,后面符合条件时继续使用它;这里是在正常利用这份副本。
但304只说明这次版本比较的结果,不能证明你刚编辑的内容已经正确发布。如果预期的新内容没有出现,先记下页面地址、修改时间,并保存自己看到的页面。把这些交给网站维护者,让他对照实际发布内容,以及请求和响应里的版本信息检查。
“已有副本”不能删:它解释了没有新正文,读者为什么仍看得到网页。“版本未变”也不能缩成“网站正常”,因为比较结果与编辑的新内容是否发布,是两项不同检查。
支付通知:收到成功响应,业务结果还要另查
第二条错稿是:“付款后网站只会收到一次通知。返回200就说明订单处理成功;没有成功时再点重发。”
原文没有保证只来一次,也没把 200 当订单结果。下面的完整改稿保留通知与业务的区别:
Stripe会把支付相关事件通知网站。收到后,程序先检查签名,确认来源,再按通知内容处理相应业务。
同一个事件可能不止送来一次,几条通知也不保证按事件发生的顺序到达。网站要记录已经处理过的事件编号,避免同一事件让业务动作重复执行。不同编号有时也可能涉及重复的业务通知,需要结合业务对象编号、事件类型和处理记录检查;不能只因为属于同一订单,就把所有不同事件都丢掉。
网站给Stripe返回200等2xx成功响应,表示这次投递得到了成功响应。订单后面的动作是否完成,还要看订单和处理记录;通知投递、业务处理和顾客看到的结果可能处在不同阶段。
如果一笔业务出现多条通知,或订单结果不符合预期,先记下相关订单、出现时间和看到的异常,交给维护者对照事件编号、业务对象、事件类型及处理日志。先检查具体动作是否已经做过,不要为了试结果反复手动重发通知。
两种重复不能合成“同一订单的通知都删掉”。相同事件编号多次投递,可以对照已处理记录;不同编号则还要看业务对象与类型,可能是需要分别处理的不同事件。
Stripe 要求程序快速给出成功响应,复杂业务逻辑可能在回应后继续做,所以 2xx 不能证明业务完成。
手动重发也不会取消原来的自动重试,“点重发试一下”可能又增加通知。成功响应、重复事件与重试规则是原文要求先留记录、再查具体业务的依据。
最后只对照原文检查一次
两段新稿应能找回这些具体意思:
- P1 的前提和结果:已有副本、带版本比较、未变时 304 无新正文、沿用副本。
- P1 的发布与求助:304 不证明新文已发布;网址、修改时间和看到的页面交维护者。
- P2 的来源与重复:处理前验签;可能重复、不保序;事件编号与业务对象、类型分开检查。
- P2 的完成与异常:2xx 不是订单全完成;保订单、时间、异常和日志检查,不反复重发。
少了哪项,就指出原句和新句,只补这一处。比如原文没讲请求条件,只写“返回304”,应先问维护者这句话描述哪次请求;原文和官方资料冲突时,把两处具体说法一起交给他,不用“通常如此”选一边。
读者仍不懂某个词,可以按 W3C 的清楚用词指导用常见词补解释,而不是删掉判断。例如“副本”可说成“浏览器先前保存的那份网页”。再按高质量内容的判断方法看读者能否执行下一步;旧文涉及事实变化时,用旧文更新的方法确定修改范围。
需要一起整理说明,可以通过联系页提供允许分享的原段、目标读者和最难懂的两句话,把事实说清后再改表达。
常见问题
改稿是不是越短越好?
看判断是否完整,不按字数决定。删成“304是正常的”虽短,却没解释为何没有新正文仍能显示。保留必要前提和原因,再删重复及空话。
我自己也看不懂原文,可以让 AI 解释后直接用吗?
先把它当候选理解,带着原文和不明白的那句话问维护者。条件不明、数字缺来源或两段冲突时,要先确认原意;模型自己的解释不能证明技术含义正确。
专业词能不能全部删掉?
不用全部删除。304、Webhook、事件编号可能是求助时需要说清的词,首次短解释后保持同一说法。重点是词后的句子讲清发生了什么,换词不能改变条件和结论。