今天一行 Java 都没写。前 12 天写的是功能接口、鉴权、缓存、Docker、部署。项目能跑、线上能点开但我那个仓库在 GitHub 上打开是这样的根目录一堆文件名下面没有正文。别人点进来看到.gitattributes、Dockerfile、mvnw、pom.xml然后就没然后了。所以今天的事是把仓库的门装上。README 写完提交了dc1c1ae8223 字节顺手补了建表脚本docs/sql/schema.sql。然后我干了件之前 12 天都没干过的事把自己写的东西当文档照着从头跑一遍。第二条命令就报错了。一、先看仓库里到底有什么、没有什么动手前先git ls-files数一遍资产这一步不能跳过因为 README 里每句话都得指得到具体文件。.gitattributes .gitignore .mvn/wrapper/maven-wrapper.properties Dockerfile api/book.http api/day6.http api/day7.http docs/day10-mysql-index-report.md docs/day11-docker-notes.md docs/day12-deploy-notes.md mvnw mvnw.cmd pom.xml src/main/...没有README.md没有LICENSE。这里有个我没想到的点根目录明明躺着一个HELP.md但git ls-files里没有它。翻.gitignore第一行就是HELP.md。Spring Initializr 生成项目时自己把它加进忽略列表了所以我磁盘上一直有仓库里从来没有。这条直接决定了一件事README 里绝对不能链HELP.md。链了就是 404而且是在公众页面上 404。二、我一开始图省事从答案纸里整段复制昨天那份答案纸是 HTML代码块都排好了看起来复制粘贴就完事。我确实是这么干的。打开答案纸选中## 接口一览那一整块CtrlC粘到README.md。然后提交、推送。第二天也就是现在翻 commit 里的文件才发现坏了三处。坏处一整段贴了两遍。87:## 接口一览 103:## 接口一览两个小节标题中间夹着一模一样的 9 行接口表加两行白名单说明。也就是说 GitHub 首页上会连着显示两张一样的表中间隔一个标题。原因很简单第一次粘贴时我觉得位置不对又贴了一次忘了删前一份。坏处二行内代码的反引号全没了。原文里应该是/user/regist落到文件里变成Knife4j 页面可以直接发请求。先调 /user/regist 注册一个账号登录拿 token 再调图书接口。/user/regist现在是纯文本页面上不会变灰还莫名其妙断成了两行。坏处三加粗被剥掉留下散装换行。MySQL 和 Redis 跑在同一个自定义网络里 不对公网暴露端口 。一个句号单独占一行。原文是**不对公网暴露端口**b标签在复制过程中被吃掉了只剩下标签两侧的换行。三处坏在同一个地方我复制的是浏览器渲染出来的样子不是 markdown 源码。HTML 里的code、b是标签剪贴板带走的是它们的样子不是 markdown 的反引号和星号。而且提交前我跑过一次git diff --stat看到「1 file changed, 219 insertions」就满意了。行数对不代表内容对我一次都没往上滚着读过。三、改成一块一块写写完自己读一遍README 不该当说明书从「环境要求」开始写。它只有三种读者耐心都短读者停留时间他心里在问对应区块面试官 / HR 扫主页30 秒这是什么能点开吗用的东西对口吗第一屏一句话 在线地址 徽章想跑起来的人5 分钟要装什么改哪一条命令能起吗快速开始想知道你怎么想的1 分钟为什么这么分层坑在哪关键设计 docs 索引顺序就是倒金字塔能看的往上能跑的中间能懂的往下。第一屏必须出现三样东西标题、一句话定位、在线地址。技术栈和架构图全部往下压因为读者是从上往下扫的。真正花时间的不是打字是每写一句回去确认一次。比如「技术栈」那张表我一开始凭印象写了 Spring Boot 3.x翻pom.xml才发现是 4.1.1。MyBatis-Plus 3.5.17、jjwt 0.12.6、Knife4j 5.7.7 全是照pom.xml抄的一个都不敢记。「功能」那张表我多加了一列「实现要点」。只写「支持增删改查」谁都能写写上「MyBatis-Plus / 拦截器 / Spring Cache」别人才知道这些我真用过。架构图用的是 mermaid写在 markdown 里 GitHub 自己渲染不用截图HTTP :8080MyBatis-PlusSpring Cache浏览器 / Knife4jbook-systemSpring Boot 4book-mysqlMySQL 8.0book-redisRedis 7三个硬细节围栏语言必须小写写mermaid整个代码块不能缩进[(...)]是数据库的圆柱形状[...]是普通方框。接口表改完之后只留一份长这样## 接口一览 | 方法 | 路径 | 说明 | 需要 token | | --- | --- | --- | --- | | POST | /user/regist | 注册 | 否 | | POST | /user/login | 登录返回 token | 否 | | GET | /user/info | 当前登录人信息 | 是 | | GET | /books | 图书列表可选 uid / status / keyword | 是 | | GET | /books/{bid} | 图书详情 | 是 | | POST | /books | 新增图书 | 是 | | PUT | /books/{bid} | 修改图书 | 是 | | DELETE | /books/{bid} | 删除图书 | 是 | | GET | /hello | 连通性自检返回固定 JSON | 否 | 白名单在 config/WebMvcConfig.java 里除了上表标否的三个 文档页面本身/doc.html、/webjars/**、/v3/api-docs/**也放行了。我数过一遍正好 9 个/books下面 5 个/user3 个/hello1 个。多出来的那份到现在还没删。写这篇文章的时候仓库 HEAD 还是dc1c1ae第 87 行和第 103 行两个## 接口一览都还在你去 GitHub 上看能直接看到两张一样的表。四、按自己写的文档跑一遍第 2 条命令就挂了README 的「快速开始」五步我从第 1 步开始照抄一个字没改。第 1 步是准备环境跳过。第 2 步是建库建表我写的是mysql-uroot-pdocs/sql/schema.sql在 PowerShell 里敲下去命令根本没执行直接在解析阶段被拒所在位置 行:508 字符: 67 ... cation D:\mywebapps\book-system-boot; try { mysql -uroot -p docs/sq ... ~ “”运算符是为将来使用而保留的。 CategoryInfo : ParserError: (:) [], ParentContainsErrorRecordException FullyQualifiedErrorId : RedirectionNotSupported注意ParserError和RedirectionNotSupported。这不是 mysql 报的错是 PowerShell 5.1 自己在解析时就不认。它压根没把命令交给 mysql。我写文档的时候脑子里想的是 bash写惯了command file。但读我 README 的人如果跟我一样用 Windows这行必然挂。能跑的写法是管道Get-Contentdocs\sql\schema.sql|mysql-uroot-p或者显式换 shellcmd/cmysql -uroot -p docs\sql\schema.sql第 3 步我没敢跑。docs/sql/schema.sql开头两句是DROP TABLE IF EXISTS book;和DROP TABLE IF EXISTS sys_user;。我本地库里现在有 7 本书、5 个用户stu31551、day7test、day7test2那几个跑完就只剩 3 本演示书加一个demo账号。写文档的人自己不敢照文档跑这就是问题。正确的做法应该是给脚本加个开关或者在 README 里明说「这个脚本会清空这两张表」。我当时只想着让别人能跑起来没想到会把自己库里的东西删掉。五、几个我当时没想通的点1. 成功码是 1不是 200。差一点就顺手写成{code:200}了模板都这么写。翻Result.java才确认success()里setCode(1)error()里setCode(0)。这是 Day 3 就定下的约定写文档时全忘。2. 演示账号的密码哈希我算了一遍。schema.sql里那行是INSERT INTO sys_user VALUES (1,demo,62cc2d8b4bf2d8728120d052163a77df)注释说密码是demo123。这种「看起来对」的东西最坑人我拿 python 算了一遍62cc2d8b4bf2d8728120d052163a77df对得上。要是当时手抄错一个字符别人照着 README 登录就会一直提示密码错误而我永远不知道。3. 不配环境变量启动会报什么。README 里写password: ${DB_PASSWORD:}冒号后面是空的。我一开始不确定这算不算「配错了也能启动」。实测ERROR 1045 (28000): Access denied for user rootlocalhost (using password: NO)using password: NO这几个字说明它真的用了空密码去连然后被 MySQL 拒绝。也就是说空默认值换来的结果是启动时明确报错而不是悄悄拿一个写死的密码连上去。这个设计我认。4. 删掉那一行密码只是止损。git log -p --all -- src/main/resources/application.yaml | grep -c password: szx跑出来是7。历史提交里还有 7 处明文。仓库是 public被爬过的收不回来。真正的补救是换密码Day 12 在服务器上换过了本地这个密码继续用不影响别人。5. README 写 JDK 17我机器上跑的是 26。.\mvnw -v的输出Apache Maven 3.9.16 Java version: 26.0.1, vendor: Oracle CorporationREADME 那行「JDK 17」是项目要求的最低版本不是我本机的实际版本。这两件事在文档里最好分开写不然别人以为必须装 17。六、能对照的期望值这几条是我实际跑出来的不是抄的检查命令期望我实测线上文档活着curl.exe -s -o NUL -w %{http_code} http://81.71.101.43:8080/doc.html2002000.29 秒徽章不是破图curl -o /dev/null -w %{http_code} https://img.shields.io/badge/Spring_Boot-4.1.1-6DB33F2002005 个徽章都能取同上换另外 4 个 URL全 200全 200演示账号密码md5(“demo123”)62cc2d8b…77df一致空密码被拒mysql -uroot --password -e select 11045using password: NO包装器能用.\mvnw -v打印版本Maven 3.9.16 / Java 26.0.1历史里还有旧密码git log -p --all -- .../application.yaml | grep -c password: szx大于 07PowerShell 里curl是Invoke-WebRequest的别名喂它-s -o -w会直接报参数错所以要写curl.exe。Git Bash 里用curl没问题把NUL换成/dev/null。七、报错对照表现象原因怎么处理运算符是为将来使用而保留的RedirectionNotSupportedPowerShell 不支持重定向Get-Content x.sql | mysql -uroot -p或cmd /c mysql ... x.sqlGitHub 首页同一张接口表出现两次同一段粘了两遍grep -n ^## README.md里搜重复标题行内代码显示成普通文字从 HTML 复制反引号是标签不是字符手打反引号或者先把答案纸的源码复制下来一句话被拆成三行句号单独一行b被剥掉标签两侧的换行留下了提交前往上滚着读一遍别只看--stat链HELP.md打开 404HELP.md在.gitignore第一行仓库里没有链到docs/下的文件mermaid 显示成一坨原始代码围栏写成 Mermaid 或者代码块整体缩进了语言名小写、顶格写徽章是破图shields.io 路径里空格没写成_Spring_Boot而不是Spring Boot本地改了 yaml线上没变镜像没重建容器跑的旧镜像重新docker builddocker rungit status冒出.idea/、target/.gitignore被改坏先别提交回头看忽略规则git push报! [rejected]远端有新提交先git pull --rebase再推别--force八、下一篇答案纸给的 Day 14 是简历和投递基建不写代码把这三周的项目整理成一份能投的稿子把 PDF、三平台账号、投递记录表搭起来。我原本以为下一篇会是给接口补 MockMvc 测试README的 TODO 第一条就是这个但顺序上简历更急测试往后放。等真动手了再写测试那篇现在写只能编。今天真正花时间的不是 README 本身是逼自己把 12 天讲一遍。讲不清的地方有三处成功码为什么是 1、/hello那几个字段为什么是 null、白名单到底放行了哪些路径。这三处我都回去翻代码才写对。README 只是结果翻代码才是过程。把这三周的项目整理成一份能投的稿子把 PDF、三平台账号、投递记录表搭起来。我原本以为下一篇会是给接口补 MockMvc 测试README的 TODO 第一条就是这个但顺序上简历更急测试往后放。等真动手了再写测试那篇现在写只能编。今天真正花时间的不是 README 本身是逼自己把 12 天讲一遍。讲不清的地方有三处成功码为什么是 1、/hello那几个字段为什么是 null、白名单到底放行了哪些路径。这三处我都回去翻代码才写对。README 只是结果翻代码才是过程。