os.ReadDir 更轻量但不递归，适合一级目录列表；需递归时用 filepath.WalkDir；元数据存 SQLite 而非 JSON；http.FileServer 必加路径校验中间件；预览应异步生成并缓存。
用 os.ReadDir 读目录比 filepath.Walk 更轻量，但不递归
如果你只是列出某个文档根目录下的 PDF、MD 文件，不需要深入子文件夹，os.ReadDir 是更快、更可控的选择。它返回 fs.DirEntry 切片，不加载完整 fs.FileInfo，省 I/O 开销。
常见错误是误以为它能递归遍历——它不能。一旦你写 os.ReadDir("docs") 却发现子目录里的文档没被扫描到，就是掉进这个坑了。
- 用
os.ReadDir适合：首页文档列表、按一级分类展示 - 需要递归（比如全文索引）时，换
filepath.WalkDir，它支持自定义fs.WalkDirFunc过滤和中断 -
os.ReadDir返回的DirEntry.Name()不带路径，拼接完整路径得手动加filepath.Join(root, entry.Name())
存文档元数据别直接塞 JSON 文件，优先选 sqlite + go-sqlite3
小团队做文档管理系统，很容易图省事把每个文档的标题、标签、更新时间写成一个 meta_abc123.json 存在同级目录。短期可行，长期会崩：并发写入冲突、无事务、搜索慢、没法建索引。
SQLite 在单机场景下足够可靠，go-sqlite3 驱动成熟，嵌入式零部署，比自己解析一堆 JSON 文件靠谱得多。
立即学习“go语言免费学习笔记（深入）”；
- 建表至少包含：
id（主键）、path（绝对或相对路径，用于定位文件）、title、tags（JSON 字符串或单独关联表）、mtime（用time.UnixMilli存纳秒级时间戳，避免时区歧义） - 插入前用
INSERT OR REPLACE INTO docs ...避免重复，别先查再插 - 查询带标签的文档时，别用
WHERE tags LIKE '%go%'，改用json_each或拆出doc_tags关联表，否则后期数据一多就卡
http.FileServer 直接暴露静态文档有风险，必须加中间件校验权限
很多人用 http.FileServer 快速提供 PDF/MD 下载链接，但默认行为是路径穿透——请求 /../../etc/passwd 可能真返回系统文件。这不是理论漏洞，是真实可触发的错误配置。
哪怕只是内部系统，也得堵住这个口。Golang 标准库没内置路径净化中间件，得自己写一层。
- 不要直接
http.Handle("/docs/", http.FileServer(...)) - 改用自定义 handler：先用
filepath.Clean归一化请求路径，再检查是否以预设文档根目录为前缀（比如strings.HasPrefix(cleaned, docRoot)） - 如果文档需鉴权（如仅管理员可见），在中间件里查
db.QueryRow("SELECT 1 FROM docs WHERE path = ? AND is_public = 1", reqPath)，不通过就http.Error(w, "Forbidden", http.StatusForbidden)
生成文档预览时别用 exec.Command("pdftotext") 同步调用
PDF 提取文本、Markdown 渲染 HTML，这些操作 CPU 和 I/O 成本高。如果每次 HTTP 请求都 exec.Command 调外部工具并等结果返回，用户会明显感知卡顿，且并发上来容易打满 CPU 或 fork 失败。
真正可用的方案是“异步生成 + 缓存”，不是“同步执行 + 硬扛”。
- 首次访问某文档时，返回占位符（如“预览生成中…”），同时发消息到内存队列（
chan *PreviewJob）或简单用sync.Map记录待处理任务 - 后台 goroutine 消费任务，调用
pdftotext或blackfriday渲染，结果存入 SQLite 的previews表（字段含doc_id,html_content,updated_at） - 后续请求直接查
previews表；若无记录或过期（比如 7 天未更新），再触发重建
路径校验、元数据持久化、权限控制、预览异步化——这四点漏掉任一环，系统上线后都会变成半夜告警的源头。尤其 filepath.Clean 和 INSERT OR REPLACE 这类细节，不测边界 case 就看不出问题。
