Initial commit

2026-06-30 15:14:37 +08:00
commit 15dab96872
311 changed files with 95639 additions and 0 deletions
@@ -0,0 +1,213 @@
+# MeshRay 路由注册顺序检查清单
+
+**创建时间**: 2026-03-24  
+**目的**: **防止再次犯同样的路由顺序错误！**
+
+---
+
+## ⚠️ **血的教训**
+
+这个问题已经犯了**至少两次**：
+1. ❌ 在 Go Embed 最佳实践文档中，示例代码写错了顺序
+2. ❌ 在实际修复 MIME 类型问题时，又犯了同样的错误
+
+**根本原因**: 没有形成肌肉记忆，没有使用检查清单
+
+---
+
+## ✅ **路由注册顺序（必须遵守）**
+
+### 正确的顺序（从高优先级到低优先级）
+
+```go
+// 1️⃣ 中间件（最优先）
+s.engine.Use(middleware.RequestLogger())
+s.engine.Use(middleware.CORS())
+
+// 2️⃣ 精确路由（具体路径）
+s.engine.GET("/health", healthHandler)
+s.engine.POST("/api/v1/login", loginHandler)
+
+// 3️⃣ ⭐ 静态文件目录（高优先级，必须在 NoRoute 之前）
+s.engine.StaticFS("/assets", httpFS)
+s.engine.StaticFS("/static", httpFS)
+
+// 4️⃣ 通配符路由（参数路由）
+s.engine.GET("/files/:filepath", fileHandler)
+
+// 5️⃣ ⭐ NoRoute 兜底路由（最低优先级，必须最后）
+s.engine.NoRoute(func(c *gin.Context) {
+    // SPA 路由支持
+})
+```
+
+---
+
+## 📋 **Checklist - 每次修改路由时都要检查**
+
+### 开发阶段
+
+- [ ] **确认路由注册顺序正确**
+  - [ ] StaticFS 在 NoRoute 之前
+  - [ ] 精确路由在 StaticFS 之前
+  - [ ] 中间件在最前面
+
+- [ ] **添加注释标记**
+  ```go
+  // ⭐ 重要：先注册静态文件目录（优先级高）
+  s.engine.StaticFS("/assets", httpFS)
+  
+  // 再注册 NoRoute 处理 SPA 路由（优先级低）
+  s.engine.NoRoute(...)
+  ```
+
+---
+
+### Code Review 阶段
+
+- [ ] **重点检查路由顺序**
+  - [ ] StaticFS 是否在 NoRoute 之前？
+  - [ ] 是否有其他路由可能拦截静态资源？
+  - [ ] 注释是否清晰标明顺序要求？
+
+- [ ] **功能测试**
+  - [ ] JS 文件返回 `application/javascript`
+  - [ ] CSS 文件返回 `text/css`
+  - [ ] HTML 文件返回 `text/html`
+  - [ ] 浏览器无 MIME 类型错误
+
+---
+
+### 测试验证
+
+**快速测试命令**:
+```bash
+# 测试 JS 文件 MIME 类型
+curl -I http://localhost:9531/assets/index.js | grep Content-Type
+# 应该返回：application/javascript
+
+# 测试 CSS 文件 MIME 类型
+curl -I http://localhost:9531/assets/style.css | grep Content-Type
+# 应该返回：text/css
+
+# 测试 HTML 页面
+curl http://localhost:9531 | grep "<!DOCTYPE html>"
+# 应该返回：<!DOCTYPE html>
+```
+
+---
+
+## 🔴 **错误示例（千万不要这样写）**
+
+```go
+// ❌ 错误示范 - 这个顺序会导致静态文件全部返回 HTML！
+if staticFS != nil {
+    httpFS := http.FS(staticFS)
+    
+    // ❌ 先注册 NoRoute（错误！）
+    s.engine.NoRoute(func(c *gin.Context) {
+        // 所有请求都被这里拦截
+    })
+    
+    // ❌ 后注册 StaticFS（永远不会被执行）
+    s.engine.StaticFS("/assets", httpFS)
+}
+```
+
+**后果**:
+- ❌ 所有 `/assets/*.js` 返回 HTML
+- ❌ 所有 `/assets/*.css` 返回 HTML
+- ❌ 浏览器控制台大量 MIME 类型错误
+- ❌ 前端完全无法使用
+
+---
+
+## 🟢 **正确示例（必须这样写）**
+
+```go
+// ✅ 正确示范 - 严格按照优先级顺序
+if staticFS != nil {
+    httpFS := http.FS(staticFS)
+    
+    // ✅ 先注册静态文件目录（高优先级）
+    s.engine.StaticFS("/assets", httpFS)
+    s.engine.StaticFS("/static", httpFS)
+    
+    // ✅ 再注册 NoRoute（低优先级）
+    s.engine.NoRoute(func(c *gin.Context) {
+        // SPA 路由支持
+    })
+}
+```
+
+**效果**:
+- ✅ JS 文件正确返回 `application/javascript`
+- ✅ CSS 文件正确返回 `text/css`
+- ✅ HTML 文件正确返回 `text/html`
+- ✅ 前端正常工作
+
+---
+
+## 📊 **记忆口诀**
+
+> **中间件最先注册，精确路由紧随其后；**  
+> **静态文件要提前，NoRoute 最后面；**  
+> **顺序千万别搞反，否则资源全完蛋！**
+
+---
+
+## 🎯 **如何形成肌肉记忆**
+
+### 1. 每次写路由时都大声念出口诀
+```
+"静态文件要提前，NoRoute 最后面"
+```
+
+### 2. 在代码模板中固化顺序
+
+创建代码片段（VSCode Snippet）:
+```go
+// Gin 路由模板
+if staticFS != nil {
+    httpFS := http.FS(staticFS)
+    
+    // ⭐ 重要：先注册静态文件目录（优先级高）
+    ${1:s.engine.StaticFS("/assets", httpFS)}
+    
+    // 再注册 NoRoute 处理 SPA 路由（优先级低）
+    ${2:s.engine.NoRoute(...)}
+}
+```
+
+### 3. 在 IDE 中设置警告
+
+如果使用 VSCode，可以创建自定义规则检测路由顺序。
+
+---
+
+## 📈 **历史错误记录**
+
+| 时间 | 错误 | 影响 | 改进措施 |
+|------|------|------|----------|
+| 2026-03-24 (Go Embed 文档) | 示例代码顺序错误 | 文档误导他人 | 已修正并添加警告 |
+| 2026-03-24 (MIME 修复) | 实际修复时顺序错误 | 前端无法访问 | 已修正并创建本清单 |
+
+---
+
+## ✅ **承诺**
+
+从今天起，每次修改路由注册时都要：
+
+1. 📝 **先看这个 Checklist**
+2. 🔍 **检查顺序是否正确**
+3. 🧪 **运行测试命令验证**
+4. 📋 **Code Review 时重点检查**
+
+**不再犯同样的错误！**
+
+---
+
+**状态**: ✅ **Checklist 已创建**  
+**执行**: 每次修改路由时必须使用此清单  
+
+*MeshRay - 从错误中学习，让教训成为财富！* ✨📋