基础开发规范

1. 项目结构

1.1 目录结构

backend/       # 后端代码
  app/         # 应用代码
    adminapi/  # 后台API
      config/  # 配置文件
      route/   # 路由配置
      middleware.php  # 中间件配置
    api/       # 前台API
      config/  # 配置文件
      controller/  # 控制器
      middleware/  # 中间件
      route/   # 路由配置
      middleware.php  # 中间件配置
    command/   # 命令行工具
    dict/      # 字典配置
    job/       # 定时任务
    lang/      # 语言文件
    listener/  # 事件监听器
    model/     # 数据模型
    validate/  # 数据验证
    AppService.php  # 应用服务
    ExceptionHandle.php  # 异常处理
    Request.php  # 请求处理
    common.php  # 公共函数
    event.php  # 事件配置
    middleware.php  # 中间件配置
    provider.php  # 服务提供者
    service.php  # 服务配置
  config/      # 配置文件
  core/        # 核心功能
    base/      # 基础类
    job/       # 任务调度
    loader/    # 加载器
    oauth/     # 第三方授权
    pay/       # 支付功能
    template/  # 模板处理
    upload/    # 文件上传
    util/      # 工具类
  public/      # 公共文件
  vendor/      # 第三方依赖
frontend/      # 前端代码
  admin/       # 后台管理系统
  uni-app/     # 移动端应用
  web/         # Web端应用
doc/          # 文档
  data/        # 文档数据
  sql/         # SQL文件

1.2 模块划分

后端模块：
- adminapi：后台管理API，处理后台管理相关的请求
- api：前台API，处理用户端相关的请求
- model：数据模型，定义数据库表结构和操作方法
- validate：数据验证，验证请求数据的合法性
- dict：字典配置，定义系统中使用的常量和配置
- job：定时任务，处理需要定时执行的操作
- command：命令行工具，提供命令行操作接口
前端模块：
- admin：后台管理系统，提供管理员操作界面
- uni-app：移动端应用，支持多端发布
- web：Web端应用，提供PC端用户界面

1.3 代码组织

控制器：负责处理请求，调用服务层方法，返回响应
模型：负责数据库操作，定义数据结构和关系
验证器：负责验证请求数据的合法性
服务层：负责业务逻辑处理，协调多个模型的操作
中间件：负责请求的预处理和后处理
工具类：提供通用的工具方法

2. 开发流程

2.1 开发流程概述

mermaid

flowchart TD
    A[需求分析] --> B[编码实现]
    B --> C[测试验证]
    C --> D[部署上线]
    D --> E[监控维护]

    subgraph 需求分析
        A1[需求收集]
        A2[需求分析]
        A3[技术选型]
        A4[文档编写]
    end

    subgraph 编码实现
        B1[环境搭建]
        B2[代码结构]
        B3[核心功能]
        B4[辅助功能]
        B5[单元测试]
    end

    subgraph 测试验证
        C1[功能测试]
        C2[性能测试]
        C3[安全测试]
        C4[兼容性测试]
    end

    subgraph 部署上线
        D1[代码审查]
        D2[环境配置]
        D3[部署发布]
    end

    subgraph 监控维护
        E1[运行监控]
        E2[问题处理]
        E3[性能优化]
    end

2.2 详细开发流程

2.2.1 需求分析

需求收集：收集业务需求，了解功能要求和业务逻辑
需求分析：分析需求的可行性和实现方案
技术选型：选择适合的技术方案和实现方式
文档编写：编写需求文档和技术方案文档

2.2.2 编码实现

环境搭建：配置开发环境，安装依赖
代码结构：按照项目结构创建相应的文件和目录
核心功能：实现核心功能模块
辅助功能：实现辅助功能和工具方法
单元测试：编写单元测试，确保功能正常

2.2.3 测试验证

功能测试：测试各项功能是否正常工作
性能测试：测试系统性能和响应速度
安全测试：测试系统的安全性和防护能力
兼容性测试：测试系统在不同环境下的兼容性

2.2.4 部署上线

代码审查：审查代码质量和安全性
环境配置：配置生产环境和部署参数
部署发布：将代码部署到生产环境
监控维护：监控系统运行状态，及时处理问题

3. 技术栈

3.1 后端技术

PHP 7.4+：主要开发语言
ThinkPHP 6.0+：PHP框架
MySQL 5.7+：数据库
Redis：缓存服务
Composer：依赖管理工具

3.2 前端技术

Vue 3：前端框架
TypeScript：类型安全的JavaScript超集
Tailwind CSS：实用优先的CSS框架
Uni-app：跨平台应用开发框架
NPM：前端依赖管理工具

3.3 工具链

Git：版本控制工具
VS Code：代码编辑器
Postman：API测试工具
Navicat：数据库管理工具

4. 配置管理

4.1 环境配置

.env文件：管理环境变量，不同环境使用不同的配置文件

// .env文件示例
APP_ENV=development
APP_DEBUG=true
APP_KEY=your_app_key

DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=niucloud
DB_USERNAME=root
DB_PASSWORD=root

配置文件：位于 backend/config/ 目录，包含各种配置项

php

// 数据库配置示例
return [
    'default' => [
        'type' => 'mysql',
        'hostname' => env('DB_HOST', '127.0.0.1'),
        'database' => env('DB_DATABASE', 'niucloud'),
        'username' => env('DB_USERNAME', 'root'),
        'password' => env('DB_PASSWORD', 'root'),
    ]
];

4.2 数据库配置

数据库连接：配置数据库连接参数
数据表结构：使用ThinkPHP的迁移工具管理数据表结构
数据填充：使用ThinkPHP的种子工具填充测试数据

4.3 缓存配置

Redis配置：配置Redis连接参数
缓存策略：制定合理的缓存策略，提高系统性能
缓存清理：实现缓存的自动清理和手动清理机制

5. 接口规范

5.1 RESTful API

HTTP方法：使用GET、POST、PUT、DELETE等HTTP方法
资源路径：使用小写字母，单词之间用连字符分隔
版本控制：在URL中包含版本号，如 /api/v1/users

5.2 响应格式

json

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "name": "John Doe"
  }
}

code：状态码，200表示成功，其他表示错误
message：消息，成功时为"success"，错误时为错误信息
data：数据，成功时返回请求的数据，错误时可以为空

5.3 错误处理

错误码：使用HTTP状态码和自定义错误码
错误信息：清晰明确的错误描述
错误日志：记录详细的错误信息，便于排查问题

6. 安全规范

6.1 数据安全

密码加密：使用bcrypt等安全算法加密存储密码
敏感数据：敏感数据脱敏处理，如手机号、身份证号等
数据备份：定期备份数据库和重要文件

6.2 接口安全

API认证：使用JWT等方式进行API认证
请求频率限制：限制API请求频率，防止恶意请求
防CSRF攻击：实现CSRF保护机制
输入验证：对所有用户输入进行验证，防止注入攻击

6.3 服务器安全

防火墙配置：配置服务器防火墙，限制访问
定期安全扫描：定期进行安全扫描，发现和修复安全漏洞
及时更新：及时更新系统和依赖包，修复已知漏洞

7. 日志管理

7.1 日志配置

日志级别：设置合理的日志级别，如debug、info、warn、error
日志存储：配置日志存储路径和格式
日志轮转：配置日志轮转策略，避免日志文件过大

7.2 日志内容

操作日志：记录用户的操作行为，如登录、修改数据等
错误日志：记录系统错误和异常
访问日志：记录API的访问情况，如请求参数、响应时间等

7.3 日志分析

日志统计：统计日志中的关键信息，如错误率、访问量等
异常监控：监控系统异常，及时发现和处理问题
性能分析：分析系统性能，找出性能瓶颈

8. 文档规范

8.1 代码文档

类注释：使用PHPDoc格式注释类的功能和用途
方法注释：使用PHPDoc格式注释方法的参数、返回值和功能
接口文档：使用Swagger等工具生成API接口文档

8.2 项目文档

需求文档：详细描述项目需求和功能点
设计文档：描述系统架构和设计方案
部署文档：描述系统的部署步骤和环境要求
用户文档：描述系统的使用方法和注意事项

8.3 文档更新

及时更新：代码变更时及时更新相关文档
版本控制：对文档进行版本控制，保持与代码版本一致
文档审查：定期审查文档的准确性和完整性

9. 开发工具和流程

9.1 开发工具

IDE：推荐使用VS Code，安装必要的插件
版本控制：使用Git进行版本控制
代码规范：使用ESLint、PHP_CodeSniffer等工具检查代码规范
测试工具：使用PHPUnit、Jest等工具进行测试

9.2 开发流程

创建分支：从主分支创建开发分支
编写代码：在开发分支上编写代码
提交代码：提交代码到开发分支
代码审查：进行代码审查，确保代码质量
合并分支：将开发分支合并到主分支
部署测试：部署到测试环境进行测试
部署生产：部署到生产环境

9.3 代码审查

代码风格：检查代码是否符合编码规范
功能实现：检查功能是否按照需求实现
安全性：检查代码是否存在安全漏洞
性能：检查代码是否存在性能问题

10. 示例代码

10.1 后端控制器示例

php

<?php
namespace app\adminapi\controller\sys;

use app\adminapi\controller\BaseController;
use app\model\sys\SysConfig;

/**
 * 系统配置控制器
 */
class Config extends BaseController {
    /**
     * 获取网站设置
     */
    public function getWebsite() {
        $configModel = new SysConfig();
        $websiteConfig = $configModel->getConfig('website');
        return success($websiteConfig);
    }
    
    /**
     * 设置网站设置
     */
    public function setWebsite() {
        $data = $this->request->param();
        $configModel = new SysConfig();
        $result = $configModel->setConfig('website', $data);
        return success($result);
    }
}

10.2 前端组件示例

vue

<template>
  <div class="sys-config">
    <el-form :model="form" label-width="120px">
      <el-form-item label="网站名称">
        <el-input v-model="form.name" placeholder="请输入网站名称"></el-input>
      </el-form-item>
      <el-form-item label="网站域名">
        <el-input v-model="form.domain" placeholder="请输入网站域名"></el-input>
      </el-form-item>
      <el-form-item>
        <el-button type="primary" @click="submitForm">保存</el-button>
      </el-form-item>
    </el-form>
  </div>
</template>

<script setup>
import { ref, onMounted } from 'vue';
import { getWebsite, setWebsite } from '@/api/sys';

const form = ref({
  name: '',
  domain: ''
});

onMounted(async () => {
  const res = await getWebsite();
  if (res.code === 200) {
    form.value = res.data;
  }
});

const submitForm = async () => {
  const res = await setWebsite(form.value);
  if (res.code === 200) {
    ElMessage.success('保存成功');
  }
};
</script>

<style scoped>
.sys-config {
  padding: 20px;
}
</style>

10.3 数据库迁移示例

php

<?php
use think\migration\Migrator;
use think\migration\db\Column;

class CreateSysConfig extends Migrator {
    public function change() {
        $table = $this->table('sys_config');
        $table->addColumn('key', 'string', ['limit' => 100, 'comment' => '配置键'])
              ->addColumn('value', 'text', ['comment' => '配置值'])
              ->addColumn('type', 'string', ['limit' => 50, 'comment' => '配置类型'])
              ->addColumn('create_time', 'integer', ['comment' => '创建时间'])
              ->addColumn('update_time', 'integer', ['comment' => '更新时间'])
              ->create();
    }
}

Admin 端

UniApp 端

基础开发规范 ​

1. 项目结构 ​

1.1 目录结构 ​

1.2 模块划分 ​

1.3 代码组织 ​

2. 开发流程 ​

2.1 开发流程概述 ​

2.2 详细开发流程 ​

2.2.1 需求分析 ​

2.2.2 编码实现 ​

2.2.3 测试验证 ​

2.2.4 部署上线 ​

3. 技术栈 ​

3.1 后端技术 ​

3.2 前端技术 ​

3.3 工具链 ​

4. 配置管理 ​

4.1 环境配置 ​

4.2 数据库配置 ​

4.3 缓存配置 ​

5. 接口规范 ​

5.1 RESTful API ​

5.2 响应格式 ​

5.3 错误处理 ​

6. 安全规范 ​

6.1 数据安全 ​

6.2 接口安全 ​

6.3 服务器安全 ​

7. 日志管理 ​

7.1 日志配置 ​

7.2 日志内容 ​

7.3 日志分析 ​

8. 文档规范 ​

8.1 代码文档 ​

8.2 项目文档 ​

8.3 文档更新 ​

9. 开发工具和流程 ​

9.1 开发工具 ​

9.2 开发流程 ​

9.3 代码审查 ​

10. 示例代码 ​

10.1 后端控制器示例 ​

10.2 前端组件示例 ​

10.3 数据库迁移示例 ​

基础开发规范

1. 项目结构

1.1 目录结构

1.2 模块划分

1.3 代码组织

2. 开发流程

2.1 开发流程概述

2.2 详细开发流程

2.2.1 需求分析

2.2.2 编码实现

2.2.3 测试验证

2.2.4 部署上线

3. 技术栈

3.1 后端技术

3.2 前端技术

3.3 工具链

4. 配置管理

4.1 环境配置

4.2 数据库配置

4.3 缓存配置

5. 接口规范

5.1 RESTful API

5.2 响应格式

5.3 错误处理

6. 安全规范

6.1 数据安全

6.2 接口安全

6.3 服务器安全

7. 日志管理

7.1 日志配置

7.2 日志内容

7.3 日志分析

8. 文档规范

8.1 代码文档

8.2 项目文档

8.3 文档更新

9. 开发工具和流程

9.1 开发工具

9.2 开发流程

9.3 代码审查

10. 示例代码

10.1 后端控制器示例

10.2 前端组件示例

10.3 数据库迁移示例