From 72497d8dc15903b8e64aac067d9eb53744676c42 Mon Sep 17 00:00:00 2001
From: wonder <hezhaohui0807@163.com>
Date: Sat, 23 May 2026 12:19:33 +0800
Subject: [PATCH] =?UTF-8?q?doc:=20=E5=A2=9E=E5=8A=A0=E4=BB=A3=E7=A0=81?=
 =?UTF-8?q?=E6=B3=A8=E9=87=8A?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 backend/cmd/main.go                |  6 ++++--
 backend/internal/config/config.go  |  9 ++++++---
 backend/internal/handler/health.go |  1 +
 backend/internal/model/response.go | 10 +++++++---
 4 files changed, 18 insertions(+), 8 deletions(-)

diff --git a/backend/cmd/main.go b/backend/cmd/main.go
index c420f0f..8e4eff5 100644
--- a/backend/cmd/main.go
+++ b/backend/cmd/main.go
@@ -1,3 +1,4 @@
+// gen2d backend 入口
 package main
 
 import (
@@ -16,9 +17,10 @@ func main() {
 	gin.SetMode(cfg.Mode)
 
 	r := gin.New()
-	r.Use(gin.Recovery())
+	r.Use(gin.Recovery()) // panic 恢复中间件，防止服务因未捕获异常宕机
 
-	r.GET("/api/v1/health", handler.Health)
+	// API v1 路由组
+	r.GET("/api/v1/health", handler.Health) // 健康检查
 
 	addr := fmt.Sprintf(":%d", cfg.Port)
 	log.Printf("gen2d backend starting on %s", addr)
diff --git a/backend/internal/config/config.go b/backend/internal/config/config.go
index 0288a3d..6254b87 100644
--- a/backend/internal/config/config.go
+++ b/backend/internal/config/config.go
@@ -1,3 +1,4 @@
+// Package config 负责从环境变量加载应用配置。
 package config
 
 import (
@@ -5,12 +6,14 @@ import (
 	"strconv"
 )
 
+// Config 应用全局配置，优先读取环境变量，未设置时使用默认值。
 type Config struct {
-	Port        int
-	Mode        string
-	MaxFileSize int64 // bytes
+	Port        int   // HTTP 监听端口，默认 8080，环境变量 GEN2D_PORT
+	Mode        string // Gin 运行模式 (debug/release)，环境变量 GEN2D_MODE
+	MaxFileSize int64  // 上传文件大小上限（字节），默认 10MB
 }
 
+// Load 从环境变量加载配置并返回。
 func Load() *Config {
 	cfg := &Config{
 		Port:        8080,
diff --git a/backend/internal/handler/health.go b/backend/internal/handler/health.go
index fd8c947..eb61746 100644
--- a/backend/internal/handler/health.go
+++ b/backend/internal/handler/health.go
@@ -6,6 +6,7 @@ import (
 	"github.com/gin-gonic/gin"
 )
 
+// Health 健康检查接口，返回服务运行状态。
 func Health(c *gin.Context) {
 	c.JSON(200, model.OK(gin.H{"status": "healthy"}))
 }
diff --git a/backend/internal/model/response.go b/backend/internal/model/response.go
index 86badbf..692eda2 100644
--- a/backend/internal/model/response.go
+++ b/backend/internal/model/response.go
@@ -1,15 +1,19 @@
+// Package model 定义请求/响应的数据结构。
 package model
 
+// Response 统一 API 响应格式，所有接口均返回此结构。
 type Response struct {
-	Code    int    `json:"code"`
-	Message string `json:"message"`
-	Data    any    `json:"data,omitempty"`
+	Code    int    `json:"code"`              // 业务状态码，0 表示成功
+	Message string `json:"message"`           // 状态描述
+	Data    any    `json:"data,omitempty"`    // 响应数据，错误时省略
 }
 
+// OK 构造成功响应。
 func OK(data any) Response {
 	return Response{Code: 0, Message: "ok", Data: data}
 }
 
+// Fail 构造错误响应。
 func Fail(code int, msg string) Response {
 	return Response{Code: code, Message: msg}
 }