feat(v1.0.4): DX & Docs 改进

按报告 v1.0.4 路线图完成 5 项开发体验与文档改进： #25 模块路径文档改进： - 保留 -core 后缀（xlgo 是多产品系列：xlgo-core/xlgo-orm/xlgo-ai） - README 快速开始补完整 import 示例 + 新增「模块路径与包名」小节 - CLAUDE.md Import Path Note 措辞明确化 #27 Without* Option 定位文档化： - 调研确认 Without* 有真实用例（测试覆盖 + NewFullStack 后排除单项） - 不删不标 Deprecated，在 app.go 注释 + README 说明其定位 #28 CLI 多模板： - xlgo new --template minimal/api/fullstack - minimal 轻量HTTP无依赖，api 标准业务分层（默认），fullstack 全组件 - 三模板实测生成正确 #29 examples/ 目录： - examples/minimal（50行可跑，无外部依赖） - examples/full（mysql+redis+jwt+user CRUD） - examples/README.md #30 文档结构： - Version_*.md + report.md 移到 docs/plans/（v2.0-review.md） - 新增 docs/README.md 索引 - CHANGELOG/GUIDE 留根目录（按惯例） - .gitignore 整理 build/vet/test + examples 编译全绿。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-22 23:21:59 +08:00
parent dcfd24b624
commit deb3cc71bf
15 changed files with 1045 additions and 31 deletions
@@ -0,0 +1,42 @@
+# xlgo 示例
+
+两个可运行示例，帮助快速上手 xlgo。
+
+## minimal — 最小 HTTP 服务
+
+不依赖 MySQL / Redis / Storage，纯 HTTP + 健康检查。第一次接触 xlgo 从这里开始。
+
+```bash
+go run ./examples/minimal
+```
+
+访问 http://localhost:8081/health（健康检查）与 http://localhost:8081/api/v1/（示例路由）。
+
+## full — 完整业务 API
+
+包含 MySQL + Redis + JWT + 一个 user CRUD（登录发 token、认证路由、创建/查询用户）。
+
+**运行前需准备**：
+- MySQL（修改 `examples/full/config.yaml` 的 `database` 配置）
+- Redis（修改 `examples/full/config.yaml` 的 `redis` 配置）
+
+```bash
+go run ./examples/full
+```
+
+启动后自动迁移 user 表。接口：
+
+| 方法 | 路径 | 说明 | 认证 |
+|---|---|---|---|
+| POST | /api/v1/login | 登录，返回 token | 否 |
+| GET  | /api/v1/users/:id | 查询用户 | 是（Bearer token） |
+| POST | /api/v1/users | 创建用户 | 是（Bearer token） |
+
+登录示例：
+```bash
+curl -X POST http://localhost:8082/api/v1/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"alice","password":"secret"}'
+```
+
+> 示例代码为演示用途，密码明文存储、未做参数校验，生产环境请使用 bcrypt 哈希密码并配合 `validation` 包校验入参。
@@ -0,0 +1,35 @@
+app:
+  name: "xlgo-full-example"
+  env: "dev"
+  debug: true
+
+server:
+  port: 8082
+  mode: development
+
+database:
+  driver: mysql
+  host: localhost
+  port: 3306
+  user: root
+  password: your_password
+  name: xlgo_example
+  max_idle_conns: 10
+  max_open_conns: 100
+
+redis:
+  host: localhost
+  port: 6379
+  password: ""
+  db: 0
+
+jwt:
+  secret: change-me-to-a-long-random-secret-at-least-32-chars
+  expire: 86400
+
+log:
+  dir: ./logs
+  max_size: 100
+  max_backups: 30
+  max_age: 30
+  compress: true
@@ -0,0 +1,125 @@
+// Package main 是 xlgo 的完整示例：MySQL + Redis + JWT + 一个 user CRUD。
+//
+// 运行前需准备：
+//   - MySQL（config.yaml 中 database 配置）
+//   - Redis（config.yaml 中 redis 配置）
+//
+// 启动后会自动迁移 user 表。访问：
+//
+//	POST /api/v1/login           {"username":"alice","password":"secret"}  → 返回 token
+//	GET  /api/v1/users/:id       （需 Authorization: Bearer <token>）
+//	POST /api/v1/users           （创建用户）
+//
+// 运行：
+//
+//	go run ./examples/full
+package main
+
+import (
+	"fmt"
+	"os"
+
+	xlgo "github.com/EthanCodeCraft/xlgo-core"
+	"github.com/EthanCodeCraft/xlgo-core/database"
+	"github.com/EthanCodeCraft/xlgo-core/jwt"
+	"github.com/EthanCodeCraft/xlgo-core/middleware"
+	"github.com/EthanCodeCraft/xlgo-core/repository"
+	"github.com/EthanCodeCraft/xlgo-core/response"
+	"github.com/EthanCodeCraft/xlgo-core/router"
+	"github.com/gin-gonic/gin"
+	"gorm.io/gorm"
+)
+
+// User 示例模型
+type User struct {
+	gorm.Model
+	Username string `gorm:"uniqueIndex;size:64" json:"username"`
+	Password string `gorm:"size:128" json:"-"` // 实际项目应存 bcrypt 哈希
+	UserType string `gorm:"size:32" json:"user_type"`
+}
+
+var userRepo *repository.BaseRepo[User]
+
+func main() {
+	app := xlgo.NewFullStack(
+		xlgo.WithConfigPath("./examples/full/config.yaml"),
+		xlgo.WithModels(&User{}),
+		xlgo.WithMiddlewares(middleware.Logger(), middleware.CORS()),
+		xlgo.WithModules(router.ModuleFunc(registerRoutes)),
+	)
+
+	// 初始化 user repository（App.Init 之后 master DB 才可用，这里在 registerRoutes 里延迟拿）
+	_ = app
+
+	if err := app.Run(); err != nil {
+		fmt.Printf("启动失败: %v\n", err)
+		os.Exit(1)
+	}
+}
+
+func registerRoutes(r *gin.RouterGroup) {
+	// 延迟初始化 repo：此时 App.Init 已完成，database.GetDB() 可用
+	userRepo = repository.NewBaseRepo[User](database.GetDB())
+
+	api := r.Group("/api/v1")
+
+	// 公开路由：登录
+	api.POST("/login", login)
+
+	// 认证路由
+	auth := api.Group("/", middleware.AuthRequired())
+	auth.GET("/users/:id", getUser)
+	auth.POST("/users", createUser)
+}
+
+func login(c *gin.Context) {
+	var req struct {
+		Username string `json:"username" binding:"required"`
+		Password string `json:"password" binding:"required"`
+	}
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.Fail(c, "参数错误")
+		return
+	}
+
+	// 示例简化：查询用户，不校验密码哈希
+	u, err := userRepo.FindOne(c.Request.Context(), "username = ?", req.Username)
+	if err != nil {
+		response.Fail(c, "用户不存在")
+		return
+	}
+
+	token, err := jwt.GenerateToken(u.ID, u.Username, "user", u.UserType)
+	if err != nil {
+		response.ServerError(c, "生成 token 失败")
+		return
+	}
+	response.Success(c, gin.H{"token": token})
+}
+
+func getUser(c *gin.Context) {
+	id := c.Param("id")
+	// 示例简化：直接用 repo 查询，实际应转 uint
+	var uid uint
+	fmt.Sscanf(id, "%d", &uid)
+	u, err := userRepo.FindByID(c.Request.Context(), uid)
+	if err != nil {
+		response.NotFound(c, "用户不存在")
+		return
+	}
+	response.Success(c, u)
+}
+
+func createUser(c *gin.Context) {
+	var u User
+	if err := c.ShouldBindJSON(&u); err != nil {
+		response.Fail(c, "参数错误")
+		return
+	}
+	u.UserType = "user"
+	if err := userRepo.Create(c.Request.Context(), &u); err != nil {
+		response.Fail(c, "创建失败: "+err.Error())
+		return
+	}
+	response.Success(c, u)
+}
@@ -0,0 +1,8 @@
+app:
+  name: "xlgo-minimal-example"
+  env: "dev"
+  debug: true
+
+server:
+  port: 8081
+  mode: development
@@ -0,0 +1,42 @@
+// Package main 是 xlgo 的最小可运行示例。
+//
+// 仅依赖一个 config.yaml，不初始化 MySQL / Redis / Storage，
+// 适合第一次接触 xlgo、或纯 HTTP 场景。
+//
+// 运行：
+//
+//	go run ./examples/minimal
+package main
+
+import (
+	"fmt"
+	"os"
+
+	xlgo "github.com/EthanCodeCraft/xlgo-core"
+	"github.com/EthanCodeCraft/xlgo-core/middleware"
+	"github.com/EthanCodeCraft/xlgo-core/response"
+	"github.com/EthanCodeCraft/xlgo-core/router"
+	"github.com/gin-gonic/gin"
+)
+
+func main() {
+	app := xlgo.New(
+		xlgo.WithConfigPath("./examples/minimal/config.yaml"),
+		xlgo.WithLogger(),
+		xlgo.WithHealthRoutes(),
+		xlgo.WithMiddlewares(middleware.Logger(), middleware.CORS()),
+		xlgo.WithModules(router.ModuleFunc(registerRoutes)),
+	)
+
+	if err := app.Run(); err != nil {
+		fmt.Printf("启动失败: %v\n", err)
+		os.Exit(1)
+	}
+}
+
+func registerRoutes(r *gin.RouterGroup) {
+	api := r.Group("/api/v1")
+	api.GET("/", func(c *gin.Context) {
+		response.Success(c, gin.H{"message": "Hello xlgo!"})
+	})
+}