后端开发规范 on Macula

API规约

Mon, 01 Jan 0001 00:00:00 +0000

本章沿用 5.x 的文档内容，尚未按 latest（当前）分支核对。涉及依赖、配置或 API 时，请以 main 分支源码为准。

概述

所有软件的UI功能都依赖于后端的API能力输出，规范的API设计以及版本管理对软件功能交付的质量与效率都至关重要。

说明：这里的API是指Restful API

设计原则

API根URL

如果预期系统非常庞大，则建议尽量将API部署到独立专用子域名（例如：“api.”）下；如果确定API很简单，不会进一步扩展，则可以考虑放到应用根域名下面（例如，“/api/”）。

 独立子域名：https://api.example.com/api/v1/*
 共享应用根域名：https://example.org/[xxx]/api/v1/* （微服务平台一般都是通过网关的统一域名对外）

API各模块URL

建议每个领域或者Controller统一一个URL根，一般的形式是：/api/v1/[xxx]，xxx表示某个领域模块名称

URI末尾不要添加“/”

多一个斜杠，语义完全不同，究竟是目录，还是资源，还是不确定而多做一次301跳转？尽量保持URI结构简洁、语义清晰。

 负面case：http://api.canvas.com/api/v1/shapes/
 正面case：http://api.canvas.com/api/v1/shapes

禁止在URL中使用“_”

目的是提高可读性，“”可能被文本查看器中的下划线特效遮蔽。建议使用连字符“-”替代下划线“”,使用“-”提高URI的可读性。

 负面case：http://api.example.com/api/v1/blogs/my_first_post
 正面case：http://api.example.com/api/v1/blogs/my-first-post

禁止使用大写字母

RFC 3986中规定URI区分大小写，但别用大写字母来为难程序员了，既不美观，又麻烦，同样的原则：建议使用连字符“-”连接不同单词。

 负面case：http://api.example.com/api/v1/My-Folder/My-Doc
 正面case：http://api.example.com/api/v1/my-folder/my-doc

不要在URI中包含扩展名

应鼓励REST API客户端使用HTTP提供的格式选择机制Accept request header。

 负面case：http://api.example.com/api/v1/my-doc/hello.json
 正面case：http://api.example.com/api/v1/my-doc/hello

建议URI中的名称使用复数

为了保持URI格式简洁统一，资源在URI中应统一使用复数形式，如需访问资源的一个实例，可以通过资源ID定位（@PathVariable）。

 负面case：http://api.college.com/api/v1/student/3248234
 正面case：http://api.college.com/api/v1/students/3248234

如何处理关联关系？

 http://api.college.com/api/v1/students/3248234/courses - 检索学生3248234所学习的所有课程
 http://api.college.com/api/v1/students/3248234/courses/physics - 检索学生3248234的所学习的物理课程

建议URI设计时只包含名词

每个URI代表一种资源或者资源集合，因此，建议只包含名词，不包含动词。

 负面case：http://api.example.com/api/v1/get-all-employees
 正面case：http://api.example.com/api/v1/employees

那么，如何告诉服务器端我们需要进行什么样的操作？CRUD？

应用分层

Mon, 01 Jan 0001 00:00:00 +0000

分层与依赖方向

业务服务可以采用经典三层作为基础组织方式：Controller → Service → Mapper → 数据库。Macula 不强制所有业务采用同一种架构；需要领域建模时，可在 Service 内进一步划分应用服务与领域能力，并保持接口和持久化边界清晰。

分层架构图

工程目录

各层职责

层次	负责什么	约束
Controller	HTTP 适配、输入校验、调用 Service	不直接访问 Mapper，不放复杂业务规则
Service / impl	业务规则、操作编排、事务	需要原子性时在公开方法声明事务，明确回滚条件
Mapper	数据访问与查询条件	使用参数绑定，限定分页、租户与数据范围
Converter	各层模型转换	沿用 MapStruct，减少手工字段复制

Controller 返回业务对象，由 Web Starter 统一封装 Result；不要重复包装或吞掉应交给统一异常处理的异常。查询与写操作分别验证权限，不能依靠前端隐藏按钮控制访问。

模型对象约定

各层模型的传递关系如下：

模型	用途	边界
Query	查询条件、分页与排序	可传递至 Service、Mapper；限制任意排序与无限结果集
Form	新增、更新等写入请求	接入 Bean Validation，不直接作为数据库实体
DTO	跨层或跨服务传输	只暴露调用方需要的字段
VO	面向调用方的展示结果	避免泄漏数据库字段与内部实现
BO	组合查询或业务处理对象	用于业务层与组合查询，不默认成为公共接口
Entity	数据库表映射	留在持久化边界内，不作为新增 REST / Feign 公共契约

不要直接将客户端提供的租户、角色或身份字段当作可信上下文。身份来自已验证的认证信息，数据范围在服务端查询中落实。

微服务规约

Mon, 01 Jan 0001 00:00:00 +0000

本章沿用 5.x 的文档内容，尚未按 latest（当前）分支核对。涉及依赖、配置或 API 时，请以 main 分支源码为准。

概述

一个微服务平台由多个模块组成，我们经过长期实践总结出一套各模块的命名规范。

微服务架构

工程目录

模块名称	说明
macula-samples-parent	父工程，定义maven依赖
macula-samples-gateway	微服务网关
macula-samples-admin-bff	管理控制台的API，聚合微服务层的接口，不会作为微服务给其他模块访问
macula-samples-openapi	给第三方平台访问的开放API
macula-samples-xxx-bff	其他前端的API层，不同前端不同的BFF模块
macula-samples-basic	微服务模块，用于基础的服务，可选项
macula-samples-thirdparty	微服务模块，用于集中访问第三方系统，防腐
macula-samples-[service1]…	具体各个业务的微服务模块，按照领域命名
macula-samples-api	微服务模块的对外SDK，其中定义了其他模块访问该模块的接口以及POJO类。
macula-samples-basic-api	basic模块的sdk
macula-samples-[service1]-api	[service1]模块的sdk

环境与配置

Mon, 01 Jan 0001 00:00:00 +0000

后端配置以 Macula Samples 当前的 application.yml 组织方式为例：公共段定义应用结构与配置导入，local 提供 IDE 本地值，docker 覆盖容器差异，共享环境通过 Nacos 管理业务配置。

完整约定、可复制的 YAML 骨架、认证地址与变量说明统一维护在application.yml 配置规范。

重点区分 Gateway 验证 IAM Token、BFF 访问 Cloud System、非网关服务验证 Samples Gateway JWT 三个方向。Java / IDE、Compose 和 Vite 对 .env 的读取方式也分别按该页说明配置。

Redis规约

Mon, 01 Jan 0001 00:00:00 +0000

本章沿用 5.x 的文档内容，尚未按 latest（当前）分支核对。涉及依赖、配置或 API 时，请以 main 分支源码为准。

概述

Redis目前已经是应对高并发、高性能场景系统设计的标配了，以下主要从键值设计、命令使用两方面对Redis的开发规范进行说明。

键值设计

key名设计

(1)【建议】: 可读性和可管理性

以业务名(或数据库名)为前缀(防止key冲突)，用冒号分隔，例如：

业务名:表名:id
ugc:video:1

(2)【建议】：简洁性

保证语义的前提下，控制key的长度，当key较多时，内存占用也不容忽视，例如：

user:{uid}:friends:messages:{mid}简化为u:{uid}:fr:m:{mid}

(3)【强制】：不要包含特殊字符

反例：包含空格、换行、单双引号以及其他转义字符

value值设计

(1)【强制】：拒绝bigkey(防止网卡流量、慢查询)

string类型控制在10KB以内，hash、list、set、zset元素个数不要超过5000。

反例：一个包含200万个元素的list。

非字符串的bigkey，不要使用del删除，使用hscan、sscan、zscan方式渐进式删除，同时要注意防止bigkey过期时间自动删除问题(例如一个200万的zset设置1小时过期，会触发del操作，造成阻塞，而且该操作不会不出现在慢查询中(latency可查))，查找方法和删除方法

(2)【推荐】：选择适合的数据类型

例如：实体类型(要合理控制和使用数据结构内存编码优化配置,例如ziplist，但也要注意节省内存和性能之间的平衡)

反例：
 set user:1:name tom
 set user:1:age 19
 set user:1:favor football
 
正例:
 hmset user:1 name tom age 19 favor football

(3)【推荐】：控制key的生命周期，redis不是垃圾桶

 建议使用expire设置过期时间(条件允许可以打散过期时间，防止集中过期)，不过期的数据重点关注idletime

命令使用

1.【推荐】 O(N)命令关注N的数量

例如hgetall、lrange、smembers、zrange、sinter等并非不能使用，但是需要明确N的值。有遍历的需求可以使用hscan、sscan、zscan代替。

2.【推荐】：禁用命令

禁止线上使用keys、flushall、flushdb等，通过redis的rename机制禁掉命令，或者使用scan的方式渐进式处理。

3.【推荐】合理使用select

redis的多数据库较弱，使用数字进行区分，很多客户端支持较差，同时多业务用多数据库实际还是单线程处理，会有干扰。

4.【推荐】使用批量操作提高效率

RocketMQ规约

Mon, 01 Jan 0001 00:00:00 +0000

本章沿用 5.x 的文档内容，尚未按 latest（当前）分支核对。涉及依赖、配置或 API 时，请以 main 分支源码为准。

命名规范

1、【强制】Topic命名：topic+下划线+业务名，例如：订单领域topic命名为：topic_order。

2、【强制】tag命名：tag+下划线+业务动作，比如：订单创建的tag为：tag_create；订单关闭的tag为：tag_close。

3、【强制】生产者分组命名：pg+下划线+业务名,例如：订单创建生产者发送订单创建消息，那么生产者分组名为：pg_order

4、【强制】消费者分组命名：cg+下划线+业务名+下划线+订阅topic名称+下划线+订阅tag名称。

例如：订单创建消息topic为topic_order，tag为tag_create，消息生产者为订单服务，用户服务和支付服务需要消费这条消息，那么用户服务的消费者分组命名为cg_user_order_create，支付服务的消费者分组命名为cg_payment_order_create。

使用规范

生产者

2.1【强制】一个领域服务只能有一个topic。

2.2【强制】领域服务发送消息时必须根据业务动作设置tag。

2.3【强制】在Producer发送消息时必须设置keys。

2.4【强制】消息发送成功或者失败要打印消息日志，务必要打印SendResult和key字段。

2.5【建议】消息发送失败后建议将消息存储到db，然后由定时器类线程进行定时重试，确保消息达到broker。

2.6【建议】对于可靠性要求不高的业务场景可以使用oneway消息。

2.7 【强制】新建生产者时必须指定生产者分组。

消费者

2.8【强制】新建消费者时必须指定消费者分组。

2.9【强制】消息消费者无法避免消息重复，所以需要业务服务来保证消息消费幂等。

2.10【建议】为了提高消费并行度，可以在同一个ConsumerGroup下启动多个Consumer实例或者通过修改ConsumeThreadMin和consumeThreadMax来提高单个Consumer的并行消费能力。

2.11【建议】为了增加业务吞吐量，可以通过设置consumer的consumeMessageBatchMaxSize来批量消费消息。

2.12 【建议】发生消息堆积时，如果业务对数据要求不高时，可以选择丢弃不重要的消息。

2.13【建议】如果消息量较少，建议在消费入口打印消息、消费耗时等，方便后续排查问题。

申请规范

3.1 【强制】在新建topic时必须进行申请，申请形式为：填写申请表，评审通过方可使用

参考

4.1 RocketMQ最佳实践