# pdf-report **Repository Path**: small_bud_star/pdf-report ## Basic Information - **Project Name**: pdf-report - **Description**: 使用Go作为后端，使用 Vue + WangEditor 作为前端，实现通过前端配置报告，导出PDF文件服务 - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-01-23 - **Last Updated**: 2026-02-04 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Go Backend API 使用 Gin 框架实现的报表生成后台服务，提供模板管理和 Mock 数据接口。 ## 技术栈 - **Go**: 1.21+ - **Web 框架**: Gin v1.9.1 - **数据库**: SQLite3 - **ORM**: 原生 database/sql - **UUID**: github.com/google/uuid v1.5.0 - **API 文档**: Swagger (swaggo/swag) ## 项目结构 ``` go-backend/ ├── config/ # 配置管理 │ └── config.go ├── database/ # 数据库相关 │ ├── database.go # 数据库连接 │ └── schema.go # 数据库表结构 ├── handlers/ # 请求处理器 │ ├── template.go # 模板相关处理器 │ └── mock.go # Mock 数据处理器 ├── models/ # 数据模型 │ ├── template.go # 模板模型 │ └── mock.go # Mock 模型 ├── routes/ # 路由配置 │ └── routes.go ├── utils/ # 工具函数 │ └── response.go # 统一响应格式 ├── go.mod # Go 模块文件 └── main.go # 程序入口 ``` ## 安装步骤 ### 前置要求 - Go 1.21 或更高版本 - SQLite3 ### 克隆项目 ```bash cd go-backend ``` ### 安装依赖 ```bash go mod download ``` ## 运行项目 ### 开发模式 ```bash go run main.go ``` ### 编译运行 ```bash go build -o server.exe ./server.exe ``` 服务默认运行在 `http://localhost:9000` ## Swagger API 文档 项目已集成 Swagger 文档，启动服务后可以通过以下地址访问： - **Swagger UI**: http://localhost:9000/swagger/index.html - **Swagger JSON**: http://localhost:9000/swagger/doc.json ### 更新 Swagger 文档 如果修改了 API 接口或注释，需要重新生成 Swagger 文档： ```bash # 首先安装 swag 工具（如果还没安装） go install github.com/swaggo/swag/cmd/swag@latest # 在项目根目录运行 swag init ``` 这将自动扫描代码中的注释并更新 `docs/` 目录下的文档文件。 ## 环境变量 可以通过环境变量配置应用： - `GIN_MODE`: Gin 运行模式 (debug/release)，默认为 debug - `PORT`: 服务端口，默认为 9000 - `DATABASE_PATH`: SQLite 数据库文件路径，默认为 ./data.db ## API 接口文档 项目已集成 Swagger，启动服务后访问 http://localhost:9000/swagger/index.html 查看完整的交互式 API 文档。 以下是主要接口的简要说明： ### 基础接口 #### 1. 根路径 ```http GET / ``` **响应示例:** ```json { "code": 200, "message": "success", "data": { "message": "Welcome to Go Backend API", "version": "1.0.0" } } ``` #### 2. 健康检查 ```http GET /health ``` **响应示例:** ```json { "code": 200, "message": "success", "data": { "status": "healthy" } } ``` ### 模板管理接口 #### 1. 创建模板 ```http POST /api/templates Content-Type: application/json { "title": "报表模板", "config": { "width": 800, "height": 600 }, "widget_list": [ { "type": "chart", "x": 10, "y": 10, "width": 300, "height": 200 } ] } ``` **响应示例:** ```json { "code": 201, "message": "success", "data": { "id": 1, "title": "报表模板", "config": { "width": 800, "height": 600 }, "widget_list": [ { "type": "chart", "x": 10, "y": 10, "width": 300, "height": 200 } ], "create_date": "2024-01-01T00:00:00Z" } } ``` #### 2. 获取模板列表 ```http GET /api/templates?page=1&page_size=10&title=报表 ``` **查询参数:** - `page`: 页码，默认 1 - `page_size`: 每页数量，默认 10，最大 100 - `title`: 标题搜索（模糊匹配） **响应示例:** ```json { "code": 200, "message": "success", "data": [ { "id": 1, "title": "报表模板", "config": {}, "widget_list": [], "create_date": "2024-01-01T00:00:00Z" } ], "total": 1, "page": 1, "per_page": 10 } ``` #### 3. 获取单个模板 ```http GET /api/templates/:template_id ``` **响应示例:** ```json { "code": 200, "message": "success", "data": { "id": 1, "title": "报表模板", "config": {}, "widget_list": [], "create_date": "2024-01-01T00:00:00Z" } } ``` #### 4. 更新模板 ```http PUT /api/templates/:template_id Content-Type: application/json { "title": "更新后的标题", "config": { "width": 1000, "height": 800 } } ``` **响应示例:** ```json { "code": 200, "message": "success", "data": { "id": 1, "title": "更新后的标题", "config": { "width": 1000, "height": 800 }, "widget_list": [], "create_date": "2024-01-01T00:00:00Z" } } ``` #### 5. 删除模板 ```http DELETE /api/templates/:template_id ``` **响应:** HTTP 204 No Content ### Mock 数据接口 #### 获取 Mock 数据 ```http GET /api/mock ``` **响应示例:** ```json { "code": 200, "message": "success", "data": { "message": "这是一个 Mock 接口返回的数据", "count": 42, "items": [ { "id": 1, "name": "项目A", "status": true }, { "id": 2, "name": "项目B", "status": false }, { "id": 3, "name": "项目C", "status": true } ], "is_active": true } } ``` ## 数据库结构 ### templates 表 | 字段 | 类型 | 说明 | | ----------- | ------- | ---------------- | | id | INTEGER | 主键，自增 | | title | TEXT | 模板标题 | | config | TEXT | 配置信息（JSON） | | widget_list | TEXT | 组件列表（JSON） | | create_date | TEXT | 创建时间 | ## 开发说明 ### 添加新的 API 接口 1. 在 `models/` 目录下定义数据模型 2. 在 `handlers/` 目录下创建处理器函数 3. 在 `routes/routes.go` 中注册路由 4. 如需数据库操作，在 `database/` 目录下添加相关函数 ### Swagger 文档注释规范 项目使用 Swagger 自动生成 API 文档。在添加新接口时，请按照以下规范添加注释： ```go // @Summary 简要描述接口功能 // @Description 详细描述接口功能和使用说明 // @Tags 接口分组标签 // @Accept json // @Produce json // @Param 参数名 参数位置 参数类型 是否必需 "描述" // @Success 200 {object} models.ResponseType "成功响应" // @Failure 400 {object} utils.Response "错误响应" // @Router /api/path [method] func HandlerFunction(c *gin.Context) { // 处理逻辑 } ``` **常用注释标签说明：** - `@Summary`: 接口的简短描述 - `@Description`: 接口的详细描述 - `@Tags`: 用于将接口分组，便于在 Swagger UI 中组织 - `@Accept`: 接受的请求类型（json、xml 等） - `@Produce`: 返回的响应类型（json、xml 等） - `@Param`: 参数说明，格式：参数名 参数位置 参数类型 是否必需 "描述" - 参数位置：`path`（路径参数）、`query`（查询参数）、`body`（请求体） - 参数类型：`string`、`int`、`bool`、`object` 等 - `@Success`: 成功响应说明，格式：状态码 {object} 响应类型 "描述" - `@Failure`: 失败响应说明 - `@Router`: 路由路径和方法 **示例：** ```go // @Summary 创建新模板 // @Description 创建一个新的报表模板，支持自定义配置和组件列表 // @Tags 模板管理 // @Accept json // @Produce json // @Param template body models.TemplateCreate true "模板信息" // @Success 201 {object} models.TemplateResponse "创建成功" // @Failure 400 {object} utils.Response "请求参数错误" // @Failure 500 {object} utils.Response "服务器内部错误" // @Router /api/templates [post] func CreateTemplate(c *gin.Context) { // 实现代码 } ``` 添加或修改注释后，运行 `swag init` 命令重新生成文档。 ### 数据库迁移 首次运行时会自动创建数据库表结构。如需修改表结构，请更新 `database/schema.go` 文件。 ## 许可证 MIT License