# 台球预约小程序项目开发规则 ## 1. 项目概述 台球预约小程序是一个基于 Go 语言后端和微信小程序前端的综合性预约平台，支持用户自动分类、预约管理、实时聊天、赛事管理等功能。本文档旨在规范项目的开发流程和代码规范，确保项目的可维护性和可扩展性。 ## 2. 技术栈 ### 2.1 后端技术栈 - **语言**: Go - **框架**: Gin - **数据库**: MySQL - **认证**: JWT + 微信小程序登录 - **权限管理**: Casbin - **实时通信**: WebSocket ### 2.2 前端技术栈 - **管理后台**: Vue3 + Element Plus - **小程序**: 微信小程序原生框架 ## 3. 项目结构规范 ### 3.1 后端项目结构 ``` . ├── config/ # 配置文件 ├── handlers/ # HTTP处理器 ├── middleware/ # 中间件 ├── models/ # 数据模型 ├── repositories/ # 数据访问层 ├── services/ # 业务逻辑服务 ├── routes/ # 路由定义 ├── utils/ # 工具函数 ├── cmd/ # 命令行工具 ├── database/ # 数据库相关 ├── docs/ # 文档 ├── api_documentation/ # API文档 ├── scripts/ # 脚本工具 ├── go.mod # Go模块定义 ├── go.sum # Go依赖锁定 ├── main.go # 应用入口 └── README.md # 项目说明 ``` ### 3.2 管理后台项目结构 ``` . ├── public/ # 静态资源 ├── src/ # 源代码 │ ├── api/ # API请求 │ ├── assets/ # 资源文件 │ ├── components/ # 公共组件 │ ├── hooks/ # 自定义钩子 │ ├── layouts/ # 布局组件 │ ├── router/ # 路由配置 │ ├── store/ # 状态管理 │ ├── utils/ # 工具函数 │ ├── views/ # 页面组件 │ ├── App.vue # 根组件 │ └── main.js # 入口文件 ├── .env # 环境变量 └── package.json # 依赖配置 ``` ### 3.3 小程序项目结构 ``` . ├── assets/ # 资源文件 ├── components/ # 公共组件 ├── config/ # 配置文件 ├── pages/ # 页面 ├── services/ # 服务 ├── utils/ # 工具函数 ├── app.js # 应用入口 ├── app.json # 应用配置 └── app.wxss # 全局样式 ``` ## 4. 编码规范 ### 4.1 Go 语言编码规范 #### 4.1.1 命名规范 - **包名**: 使用小写单词，不使用下划线或混合大小写 - **文件名**: 使用小写单词，可使用下划线分隔 - **变量名**: 使用驼峰命名法，私有变量小写开头，公有变量大写开头 - **常量名**: 使用全大写，下划线分隔 - **接口名**: 以 "er" 结尾，如 `Reader`, `Writer` - **结构体名**: 使用大驼峰命名法 #### 4.1.2 注释规范 - 所有导出的函数、类型、变量和常量都必须有注释 - 注释应该是完整的句子，以被注释对象的名称开头 - 使用 `//` 进行单行注释，使用 `/* */` 进行多行注释 #### 4.1.3 错误处理 - 错误应该被明确处理，不应该被忽略 - 使用自定义错误类型增强错误信息 - 在返回错误之前进行日志记录 #### 4.1.4 代码格式化 - 使用 `gofmt` 或 `goimports` 格式化代码 - 缩进使用制表符（tab） - 行长度不超过 100 个字符 ### 4.2 Vue/JavaScript 编码规范 #### 4.2.1 命名规范 - **组件名**: 使用 PascalCase（大驼峰），如 `UserProfile` - **文件名**: 与组件名一致，使用 PascalCase - **变量名**: 使用 camelCase（小驼峰），如 `userName` - **常量名**: 使用全大写，下划线分隔，如 `MAX_COUNT` - **CSS 类名**: 使用 kebab-case（短横线），如 `user-profile` #### 4.2.2 组件结构 - 组件按照 `<template>`, `<script>`, `<style>` 顺序排列 - 使用 `setup` 语法糖简化组件逻辑 - 组件属性按字母顺序排序 #### 4.2.3 样式规范 - 优先使用 `scoped` 样式隔离组件样式 - 使用 SCSS 预处理器提高样式复用性 - 遵循 BEM 命名规范（Block-Element-Modifier） #### 4.2.4 JavaScript 规范 - 使用 ES6+语法特性 - 优先使用箭头函数 - 使用 async/await 处理异步操作 - 使用解构赋值简化代码 ### 4.3 微信小程序编码规范 #### 4.3.1 命名规范 - **文件名**: 使用小写字母，单词间用连字符（-）分隔 - **变量名**: 使用 camelCase（小驼峰） - **常量名**: 使用全大写，下划线分隔 #### 4.3.2 WXML 规范 - 标签属性使用双引号 - 标签属性按字母顺序排序 - 使用 `wx:for` 时必须指定 `wx:key` #### 4.3.3 WXSS 规范 - 使用类选择器，避免使用标签选择器 - 使用 rpx 作为尺寸单位，确保适配不同屏幕 - 遵循移动端设计原则，确保触控区域足够大 #### 4.3.4 JavaScript 规范 - 使用 ES6+语法特性 - 避免在页面中直接操作全局数据 - 使用 Promise 处理异步操作 ## 5. 数据库规范 ### 5.1 表命名规范 - 使用小写字母，单词间用下划线分隔 - 使用复数形式命名表，如 `users`, `venues` - 关联表使用两个表名连接，如 `user_venues` ### 5.2 字段命名规范 - 使用小写字母，单词间用下划线分隔 - 主键统一命名为 `id` - 外键命名为 `表名_id`，如 `user_id` - 创建时间和更新时间分别命名为 `created_at` 和 `updated_at` ### 5.3 索引规范 - 主键索引命名为 `pk_表名` - 唯一索引命名为 `uk_表名_字段名` - 普通索引命名为 `idx_表名_字段名` ### 5.4 SQL 编写规范 - 关键字使用大写，如 `SELECT`, `INSERT`, `UPDATE` - 表名和字段名使用小写 - 使用参数化查询，避免 SQL 注入 - 复杂查询应该添加注释 ## 6. API 设计规范 ### 6.1 RESTful API 规范 - 使用 HTTP 方法表示操作类型（GET, POST, PUT, DELETE） - 使用名词复数形式作为资源名称 - 使用嵌套资源表示资源间的关系 - 使用 HTTP 状态码表示请求结果 ### 6.2 请求参数规范 - GET 请求参数使用查询字符串 - POST/PUT 请求参数使用 JSON 格式 - 参数名使用 camelCase（小驼峰） - 必填参数应该在文档中明确标注 ### 6.3 响应格式规范 - 统一使用 JSON 格式 - 响应体包含状态码、消息和数据三部分 - 分页数据包含总数、当前页码、每页数量和数据列表 - 错误响应包含错误码、错误消息和详细信息 ### 6.4 API 文档规范 - 使用 Markdown 格式编写 API 文档 - 文档包含接口名称、URL、请求方法、请求参数、响应格式和示例 - 按照功能模块组织文档结构 - 定期更新文档，确保与代码保持一致