2025-07-28 09:55:46 +08:00
2025-05-27 17:12:57 +08:00
2025-07-28 09:55:46 +08:00
2025-07-28 09:50:05 +08:00
2025-05-27 17:12:57 +08:00
2025-07-16 22:58:41 +08:00
2025-05-27 17:12:57 +08:00
2025-07-16 23:32:22 +08:00

开发技术规范文档

本规范文档适用于技术团队及新引入技术的项目落地,目标是规范化公司技术选型、架构设计、开发流程,提升质量与效率,降低技术风险。


📌 一、前言

目标与背景

规范化公司技术选型、架构设计、开发流程,提升质量与效率,降低技术风险。

适用范围

适用于技术团队及新引入技术的项目落地。


🧱 二、技术栈选型与架构概览

2.1 技术体系结构图

平台整体架构图, Web 层、服务层、硬件接口层、中间件层、存储层、第三方接入等模块交互与部署方式。

2.2 技术选型说明

模块 技术选型 说明
Web 框架 PHP + Swoole + Hyperf 高并发、协程模型,用于高性能后端服务
硬件上位机开发 C# + C++ C# 用于可视化控制界面C++ 用于底层驱动与 TCP 通信模块
前端框架 Vue 3.x + TypeScript/JavaScript + Vuex + Vue Router + Element Plus 前端开发栈,响应式与组件化开发
对外接口 RESTful API 标准化输出格式,统一鉴权方案
数据库 MySQLRDS + Redis缓存+分布式锁) 用数据库架构
中间件 RabbitMQ 异步任务队列、事件消息总线
服务发现与配置中心 Nacos 服务注册发现 + 动态配置中心
硬件通信 TCP 服务 所有硬件上位机通过统一 TCP 服务接入,遵循协议解析规范

☁️ 三、云服务与第三方服务使用规范

3.1 阿里云资源管理

  • ECS 实例命名规则<环境>-<业务>-<编号>prod-order-01
  • 资源标签管理:按业务、环境、负责人分类
  • 网络安全组规则:最小权限原则,仅开放必要端口,需开放端口时,需由技术审批

3.2 第三方基础服务

  • 阿里短信服务:统一 SDK、消息模板管理、错误码处理机制
  • e签宝电子签名:鉴权方式、回调接口、数据可追溯性管理

💰 四、采购审批流程

  • 所有第三方服务需走审批流程:技术经理 → 总监审批 → 录入内部采购系统
  • 保留完整审批链,评估成本、替代方案与风险
  • 采购记录需与采购管理系统对接

📐 五、系统设计与文档规范

5.1 需求分析文档

  • 使用统一模板,输出功能描述、用户角色、流程图、非功能性需求等

5.2 接口设计规范

  • 遵循 RESTful 设计原则
  • 使用统一接口文档框架Apipost
  • 支持自动代码生成、Mock 调试、文档同步更新
  • 硬件TCP接口使用统一接口规范签名验签

5.3 架构决策记录

  • 流程记录重大技术决策
  • 内容包括:背景、讨论、决定等

🧑‍💻 六、开发规范与代码结构

6.1 目录结构(以自动化/MES/生产系统为例)

  • 本文基于 Hyperf 官方框架结构,并结合社区最佳实践,逐一说明每个目录/文件的职责与用途。
├── .devcontainer/
├── .github/
├── app/
├── bin/
├── config/
├── migrations/
├── public/
├── runtime/
├── storage/
├── test/
├── .env.example
├── composer.json
├── phpunit.xml.dist
└── ...

6.2 Hyperf 项目目录结构详解 📁

路径 类型 功能说明
.devcontainer/ 文件夹 VS Code 容器配置,统一开发环境
.github/ 文件夹 CI/CD如 GitHub Actions、Issue 模板配置
composer.json 文件 PHP 包依赖配置
.env.example 文件 环境变量模板,供复制为 .env 使用
phpunit.xml.dist 文件 PHPUnit 测试配置
路径 类型 功能说明
app/ 文件夹 应用主要业务代码入口,包含以下子模块
app/Amqp/ 文件夹 AMQP 消息发送/消费任务类
app/Aspect/ 文件夹 AOP 切面逻辑(如日志、鉴权)
app/Command/ 文件夹 CLI 自定义命令脚本
app/Constants/ 文件夹 全局常量定义(状态码、消息类型等)
app/Context/ 文件夹 请求上下文管理(如 QID、用户信息
app/Controller/ 文件夹 HTTP 接口控制层
app/Dao/ 文件夹 直接数据库访问层封装
app/Exception/ 文件夹 自定义异常类和统一逻辑
app/Helpers/ 文件夹 通用工具函数
app/Job/ 文件夹 定时任务或队列任务执行类
app/JsonRpc/ 文件夹 JSON-RPC 接口,供硬件或外部调用
app/Listener/ 文件夹 事件监听器与触发机制
app/Log/ 文件夹 日志入口、格式化、QID 链路
app/Middleware/ 文件夹 HTTP/MQ 中间件(限流、鉴权、异常处理)
app/Model/ 文件夹 ORM 映射层,对应数据库表
app/Process/ 文件夹 自定义进程(如 Socket、守护进程
app/Repository/ 文件夹 Repository 或 DAO 层,封装 Model 调用
app/Request/ 文件夹 接口参数验证对象
app/Scope/ 文件夹 Eloquent 范畴定义global/local
app/Service/ 文件夹 业务逻辑层
app/Task/ 文件夹 异步任务,配合 Scheduler 使用
app/Utils/ 文件夹 独立于业务的工具逻辑封装
  • 代码调用层级Controller → Repository → Dao → Service → Model
  • Repository 不直接操作 DB由 Dao 统一调用 Model

6.3 命名与依赖注入

  • 类命名:以 Repository, Dao, Service, Controller, Model... 后缀命名
  • 使用 @property 注解实现隐式 DI提高 IDE 识别与导航

6.4 响应与日志规范

  • 统一响应出口:App\Utils
  • 示例代码:
namespace App\Utils;

class Response {
    public function success(array $data = [], string $message = 'Success', int $code = 200): Response
    {
        $result = [
            'code' => $code,
            'message' => $message,
            'data' => $data,
        ];

        return self::jsonResponse($result);
    }

    public function error(string $message, int $code = 0, $data = null): Response
    {
        $result = [
            'code' => $code,
            'message' => $message,
            'data' => $data,
        ];

        return self::jsonResponse($result);
    }
}
  • 中间件在请求到达 Controller 前生成 qid唯一请求 ID写入上下文日志需携带 qid 用于链路追踪

🔨 七、测试策略

  • 单元测试Service 层、关键工具类、协议解析模块覆盖。
  • 集成测试API 接口调试、数据库交互、消息队列流程。
  • 性能测试压力测试脚本wrk、Swoole 并发 benchmark。
  • 协议连通:硬件 TCP 接口测试工具、模拟场景以及并发测试。

🚫 八、安全与合规

  • 配置隔离:生产环境用配置中心读取,禁止硬编码。
  • 鉴权方式:对外接口通过 OAuth2/JWT + IP 白名单 + 签名方式同网关。
  • 硬件接入安全TCP 接口需做协议签名校验,防重放、防 DOS、防配置漏洞攻击。
  • 数据保护:敏感数据如手机号、身份证在数据库存储时采用加密。

🎓 九、文档与知识管理

  • 所有文档采用 Markdown 管理,统一托管于 Git 仓库。
  • 配合 Docsify 等文档生成方案,形成知识库。
  • 技术规范等文档均版本化管理、长期维护。

🚩 十、组织与流程管控

  • 技术规范由 技术总监 起草,由技术团队评审、讨论完善,由总监批准。
  • 新技术、新框架、新工具需要流程引入(决策/评审),并记录至技术规范文档。
  • 接口或框架调整须形成文档、明确迁移路径、兼容性策略。
Description
json-rpc服务文档
Readme 107 KiB
Languages
HTML 100%