野塘漫水

私有项目怎么写成公开技术文章 ​

真实项目比练习项目更有文章价值，因为它遇到过兼容、历史数据、弱网和多人协作等真实问题。但直接复制源码，很容易顺带公开内部接口、业务规则或用户数据。

安全写作不是把所有内容都写得模糊，而是：保留问题和解决方法，重新整理代码和数据。

读完你能解决什么 ​

  • 判断哪些项目代码可以公开；
  • 把真实代码缩成读者容易理解的示例；
  • 区分“项目已经做到”和“文章推荐这样做”；
  • 在发布前检查文本、图片和构建产物。

哪些内容不能直接发布 ​

内容常见位置处理方式
密钥、Token、证书配置、SDK、私钥文件完全删除，不做打码展示
域名、IP、端口环境配置、请求封装改成 example.test
客户和员工数据日志、接口响应、截图使用全新合成数据
内部表名和字段SQL、模型、迁移脚本为文章重新设计简单模型
真实业务常量状态码、金额、角色编码改成通用状态和演示数值
本机路径错误栈、终端、构建日志改成相对路径
内部品牌和模块类名、路由、图片使用中性名称

删除公司名还不够。一个真实接口路径、一段错误文案或一张后台截图，也可能暴露系统用途。

把“取材”和“公开文章”分开 ​

推荐准备两份内容：

text
私有源码
  ↓ 只读检查
内部底稿：记录事实和本地出处，不发布
  ↓ 提炼问题与方法
公开文章：使用重新整理的代码和合成数据

内部底稿只需要写：哪个文件证明了什么。不要把整个函数、配置值或真实日志复制进去。

底稿必须位于站点发布目录之外，并通过本地忽略规则避免被提交。

先区分三种内容 ​

已验证事实 ​

源码可以直接证明，例如：

text
项目使用 Vue 2 和 Vue Router 3。
请求统一经过一个 Axios 实例。
小程序使用 app.json 声明分包。

工程判断 ​

根据多处实现得出的结论，例如：

text
全局入口注册内容过多，会增加启动依赖和维护成本。

推荐做法 ​

文章提出的改进，不一定已经在项目落地：

text
可以增加 outbox，记录提交后仍需执行的外部任务。

文章要明确写“项目中已有”还是“建议增加”，不要把目标方案写成现状。

示例不能只改变量名 ​

假设原项目里有一段很长的提交逻辑，其中包含真实角色、业务状态和接口参数。

不推荐这样处理：

text
复制原函数
→ 把 Customer 改成 User
→ 把真实 URL 改成 demo URL
→ 其他结构全部保留

它仍可能暴露原来的控制流和特殊规则。

更安全的做法是只保留文章要解释的概念，从空文件重新写：

js
const running = Object.create(null)

export function runOnce(key, task) {
  if (running[key]) return running[key]

  const clear = () => { delete running[key] }
  const promise = Promise.resolve().then(task).then(
    value => {
      clear()
      return value
    },
    error => {
      clear()
      throw error
    }
  )
  running[key] = promise
  return promise
}

这段代码只解释“同一任务复用进行中的 Promise”，没有真实业务模型和接口。双分支清理也能兼容未提供原生 Promise.prototype.finally 的旧 WebView。

怎样展示项目代码 ​

可以展示下面几类片段：

  • 框架入口和生命周期的典型结构；
  • 通用请求、错误处理和提交锁；
  • 不含业务规则的路由拆分方式；
  • 纯函数，例如日期、金额或状态转换；
  • 为文章重新编写的最小复现测试。

每段代码前明确说明：

以下代码根据真实项目中的模式重新整理，已删除业务名称、接口参数和内部数据。

代码越短越好。读者应该一眼看出它证明什么。

示例数据要完全新建 ​

不要把真实手机号改成星号，也不要从生产日志中挑一条“看起来不敏感”的记录。

使用全新的合成数据：

json
{
  "actorId": "user_demo_17",
  "operationId": "op_demo_42",
  "status": "pending",
  "amountMinor": 12990
}

金额、时间、数量和状态都不应复刻真实分布。

地址和配置怎么写 ​

URL 使用保留用途域名：

text
https://api.example.test/v1/resources

路径使用相对目录：

text
src/modules/example/
server/Application/Example/

环境变量只展示名称和无效占位符：

dotenv
APP_ENV=development
API_BASE_URL=https://api.example.test
SESSION_SECRET=<provided-by-deployment-platform>

不要为了“示例能直接运行”放一个固定测试密钥。它很容易被复制到真实项目。

图和截图也可能泄密 ​

截图经常包含：

  • 浏览器地址栏；
  • 登录账号和通知；
  • 真实菜单、品牌和客户信息；
  • 终端用户名与绝对路径；
  • 二维码、条码和图片元数据。

最安全的方法是使用合成数据重新画一张小图：

text
页面 → 请求适配层 → 业务服务 → 数据库
                     └──────▶ 外部服务

如果必须截图，使用专门的演示环境，并检查裁剪后的原文件，而不是只看网页中的缩略图。

发布前做两种扫描 ​

敏感特征扫描 ​

在本地搜索真实项目名、域名、IP、绝对路径和密钥特征：

bash
rg -n -i \
  'private-project|internal\.example|PRIVATE KEY|API_SECRET' \
  docs/

真实敏感词清单保存在本地，不要为了扫描又把它提交到公开仓库。

与源码做长片段比对 ​

把文章中的长代码行或连续多行与私有源码做本地精确比对。如果有命中，确认它是否真的是可以公开的通用代码。

扫描报告只输出文章行号和来源文件，不要再次打印敏感原文。

还要检查构建产物 ​

Markdown 没有问题，不代表生成的网站没有问题。构建后继续检查：

  • 搜索索引是否包含内部底稿；
  • Source Map 是否带本机路径；
  • 打包后的环境变量是否含真实地址；
  • 图片附件是否带元数据；
  • 页面和导航是否存在死链。
text
扫描源文件
  → 本地构建
  → 检查构建日志
  → 扫描 dist
  → 打开关键页面
  → 查看 Git 待提交文件

一篇文章的简单生产流程 ​

  1. 先写一个通用问题，例如“弱网下怎样防止重复提交”；
  2. 只读检查直接相关的入口、工具和测试；
  3. 在内部底稿记录事实和来源；
  4. 提炼一个可以跨项目使用的不变量；
  5. 从空文件重新写最小代码；
  6. 使用合成数据和中性名称；
  7. 第一轮检查技术正确性；
  8. 第二轮只检查信息安全；
  9. 构建并扫描最终产物；
  10. 只提交公开文章和必要导航。

发布检查清单 ​

  • [ ] 文章在讲通用问题，而不是介绍私有目录；
  • [ ] 项目事实和推荐方案已经区分；
  • [ ] 代码片段足够短，并已删除业务参数；
  • [ ] 示例数据完全由作者生成；
  • [ ] 没有真实域名、IP、账号和绝对路径；
  • [ ] 图片、二维码和附件已经检查；
  • [ ] 内部底稿不在发布目录和 Git 暂存区；
  • [ ] 源文件与构建产物敏感扫描通过；
  • [ ] 站点构建和导航检查通过。

最后记住 ​

公开技术文章真正应该分享的是：问题、约束、失败原因、解决方法和验证方式。

真实代码为文章提供证据，但不必把整个真实实现搬到网上。示例越聚焦，文章越容易理解，也越安全。

为复用而记录，为理解而整理。

MIT Licensed · Copyright © 2019–present qun ye