cloud
85 lines
3.2 KiB
Markdown
85 lines
3.2 KiB
Markdown
---
|
||
name: backend-conventions
|
||
description: 后端 C++ 规范。用于修改本仓库后端接口、Controller、Manager、配置文件与接口文档时，统一 JSON 处理、字段命名、响应结构与文档同步要求。
|
||
---
|
||
|
||
# 后端规范
|
||
|
||
## JSON 规则
|
||
|
||
- 统一使用 `nlohmann/json`
|
||
- 在实现文件中统一写：`using json = nlohmann::json;`
|
||
- 禁止新增 `jsoncpp` 依赖
|
||
- 解析请求体时必须处理非法 JSON 分支
|
||
|
||
## Drogon 响应构建
|
||
|
||
- 优先复用 `ResponseUtil`，避免每个接口自行拼装响应
|
||
- 明确设置 `Content-Type: application/json`
|
||
- 可预期失败走业务错误响应，不直接向前端暴露底层异常细节
|
||
|
||
示例：
|
||
|
||
```cpp
|
||
auto resp = HttpResponse::newHttpResponse();
|
||
resp->setContentTypeCode(CT_APPLICATION_JSON);
|
||
resp->setStatusCode(k200OK);
|
||
resp->setBody(ResponseUtil::GenerateSuccessResponse(data).dump());
|
||
callback(resp);
|
||
```
|
||
|
||
## 字段命名
|
||
|
||
- 请求体、响应体、配置文件统一 `snake_case`
|
||
- 禁止在 JSON 中混用 `camelCase`
|
||
|
||
## 响应约定
|
||
|
||
- 响应结构和状态码语义以当前模块现状为准（不要凭空定义新格式）
|
||
- 错误码与错误文案保持稳定，避免前后端契约漂移
|
||
|
||
## 日志与错误信息
|
||
|
||
- 先复用同模块既有日志前缀和措辞
|
||
- 对外错误信息默认中文（除非该接口已约定英文）
|
||
- 不要无故把已有中文日志改成英文
|
||
|
||
## 文档同步
|
||
|
||
- 改后端接口时，必须同步更新该模块 `docs/接口文档.md`
|
||
- 若前端有 API 封装，同提交同步更新封装层
|
||
- 新增接口时补齐：路径、方法、参数、成功/失败示例
|
||
- **每次新增或修改协议时，必须同步更新 `collector/docs/协议支持清单.md` 文档**
|
||
- **每次新增协议或修改协议细节时，必须在 `collector/docs/protocols/` 下新增或更新对应的协议实现文档，并且文档内强制要求写入底层依赖库来源及其具体安装/编译方式**
|
||
|
||
## 协议开发规范
|
||
|
||
- **新增协议驱动时，严禁在应用层类中直接调用底层的原生 API（如原生 Socket API、原生串口操作函数等），除非有特殊需求需要和我确认。**
|
||
- **必须注入并使用通用的公共类进行通信，例如：**
|
||
- TCP 连接使用 `TcpTransport`
|
||
- UDP 连接使用 `UdpTransport`
|
||
- 串口连接使用 `SerialTransport`
|
||
- 这些类均应继承自核心抽象接口 `ITransport`。
|
||
|
||
## 协议配置规范
|
||
|
||
> 详细规则参见 `collector/docs/协议支持清单.md` 的"更新规范"章节。
|
||
|
||
### protocol_name
|
||
|
||
- 全大写 + 下划线：`MODBUS_TCP`、`FINS_TCP`
|
||
- 同一协议不同连接方式**拆分为独立条目**，后缀：`_TCP`/`_RTU`/`_SERIAL`/`_OVERTCP`
|
||
- 驱动注册标识必须与 `protocol_name` 完全一致
|
||
|
||
### brand
|
||
|
||
- 有品牌协议：使用品牌原名，不附加连接方式或描述
|
||
- 通用协议（Modbus/OPC UA）：使用标准协议名
|
||
- 无品牌行业标准：使用**应用领域**（如 `"电力仪表"`, `"水气仪表"`），避免与 protocol_name 重复
|
||
- ✅ `"西门子"`, `"电力仪表"` / ❌ `"哈斯串口"`, `"IEC104"`（与 protocol_name 冗余）
|
||
|
||
### connection_type
|
||
|
||
- 每个协议条目只允许一种 `connection_type`（`"ethernet"` 或 `"serial"`）
|
||
- 需要同时支持串口和以太网时，新增独立协议条目
|