feat: 补充部分接口设计规范说明

PMAT77 · Feb 5, 2025 · ee5f01f · ee5f01f
1 parent f635683
commit ee5f01f
Show file tree

Hide file tree

Showing 2 changed files with 20 additions and 3 deletions.
diff --git a/docs/standard/summary/api.md b/docs/standard/summary/api.md
@@ -1,9 +1,25 @@
 # 接口相关
 
-<tips type="warning">
-请检查项目接口是否遵循以下约定，如有出入请务必修改保持一致。
+<tips type="info">
+良好的接口设计应该模块化、松耦合，每个接口负责特定的功能或数据类型。
 </tips>
 
+## 接口设计
+
+**接口设计时应当避免 `字段混用`，例如销售出库单列表，避免出现领料单、到货单等不相关字段。**
+
+1. **代码可维护性**：混用大量字段会让前端代码变得复杂，难以维护。每次修改或调整都需要仔细筛选相关字段，增加了出错的风险。
+2. **性能问题**：不必要的字段会增加数据传输的开销，尤其是在网络条件较差的情况下，可能会影响应用的响应速度和用户体验。
+3. **数据冗余**：过多的字段可能导致数据冗余，增加数据库和接口的数据处理负担，影响系统的整体效率。
+4. **文档维护困难**：接口文档需要详细说明每个字段的作用和使用场景，混用大量字段会使得文档变得臃肿且难以理解，增加了沟通成本。
+
+如果需要混用字段，建议参考如下：
+
+- 分模块设计接口：将相关性高的字段放在一个接口中，将不相关的字段分散到不同的接口。
+- 补充文档说明：通过详细的接口文档明确每个字段的用途和使用场景，减少理解上的歧义。
+
+**同时也应当避免 `功能混用`，尽量保持接口功能单一。如果接口的使用场景相似，则通过 `bizType` 字段区分业务类型。**
+
 ## 常用字段名约定
 
 | 字段          | 说明           | 数据类型            | 备注                   |
@@ -15,6 +31,7 @@
 | auditUsername | 审核人：用户名 | `string`            |                        |
 | auditRealname | 审核人：姓名   | `string`            |                        |
 | bizType       | 业务类型       | `string`            | 同接口区分不同业务类型 |
+| ...           | ...            |                     |                        |
 
 ## 权限标识
 
@@ -34,7 +51,7 @@ base:materialType:add
 
 ## 错误信息
 
-对于一些可预见的错误，请返回对应通俗易懂的错误信息，方便快速定位和排查问题。
+完善全局错误处理，对于一些可预见的错误，请返回对应通俗易懂的错误信息，方便快速定位和排查问题。
 
 ## 响应体结构
 

diff --git a/docs/standard/summary/image.png b/docs/standard/summary/image.png