📚 课程目录第3章服务设计方法论

3、服务设计方法论：服务粒度划分原则、服务接口设计（IDL）、服务契约与版本管理

好，我们进入第三章。前面聊了SOA是什么、为什么智舱需要它。但真正落地的时候，第一个难题就来了：服务到底该怎么拆？

拆大了，变成“单体换皮”，没发挥出SOA的优势；拆小了，服务满天飞，调用链长到让人崩溃。我见过不少项目，前期没想清楚粒度，后期重构成本高得吓人。

这一章，我就把服务设计的核心三板斧掰开揉碎讲清楚：粒度怎么定、接口怎么设计、契约怎么管。

3.1 服务粒度划分原则

服务粒度，说白了就是一个服务“管多宽”的问题。我个人习惯用三个维度去卡：业务边界、复用潜力、变更频率。

核心原则：高内聚、低耦合、可复用。

一个服务只做一件事，并且把它做好。

3.1.1 粒度划分的“三把尺子”

维度	判断标准	举例（智舱场景）
业务边界	是否属于同一个业务领域？	“座椅调节”和“空调控制”是不同领域，应拆为两个服务。
复用潜力	是否会被多个上层应用调用？	“获取车辆位置”会被导航、安防、充电推荐共用，必须独立。
变更频率	业务逻辑是否经常变化？	“语音唤醒词”可能频繁更新，与“音频播放”这种稳定服务分开。

举个例子。我在做上一代智舱平台时，团队把“车窗控制”和“天窗控制”合并成一个“车身控制服务”。结果呢？天窗逻辑改了三次，每次都要全量回归车窗功能。后来拆成两个独立服务，各自迭代，互不干扰。

3.1.2 粒度划分的“避坑指南”

不要过度拆分：服务粒度过细，会导致服务间调用链变长，延迟增加。我曾经见过一个项目，一个简单的“开门”动作，调用了7个服务，延迟从5ms飙升到50ms。
不要“一刀切”：不同业务域的粒度标准可以不同。比如，底层硬件抽象服务可以粗一些，上层业务服务可以细一些。
考虑数据一致性：强一致性的操作，尽量放在同一个服务内，避免分布式事务的复杂性。

我曾经踩过的坑： 把“用户登录”和“用户偏好设置”放在一个服务里。后来登录逻辑要对接第三方账号，偏好设置要支持多端同步，两个需求互相阻塞，发布窗口一拖再拖。拆开之后，各自独立上线，清爽多了。

3.2 服务接口设计（IDL）

服务拆好了，怎么让别人知道怎么调用你？这就需要接口定义语言（IDL）。IDL是服务提供者和消费者之间的“合同”，它不关心你内部怎么实现，只关心你提供了什么能力。

在智舱领域，我们常用的IDL是Protobuf（Protocol Buffers）。为什么选它？性能好、跨语言、向后兼容性强。你想想看，智舱里既有C++写的底层服务，又有Java写的云端服务，还有JS写的HMI应用，Protobuf能无缝对接。

3.2.1 一个典型的Protobuf接口定义

syntax = "proto3";

package vehicle.cabin.seat;

// 座椅服务定义
service SeatService {
  // 调节座椅位置
  rpc AdjustPosition (AdjustPositionRequest) returns (AdjustPositionResponse);
  // 查询座椅当前状态
  rpc GetStatus (GetStatusRequest) returns (SeatStatus);
}

// 请求：调节座椅位置
message AdjustPositionRequest {
  int32 seat_id = 1;          // 座椅编号（1=主驾，2=副驾）
  int32 position_x = 2;       // X轴位置（mm）
  int32 position_y = 3;       // Y轴位置（mm）
  int32 recline_angle = 4;    // 靠背角度（度）
}

// 响应：调节结果
message AdjustPositionResponse {
  bool success = 1;
  string error_message = 2;
}

// 状态：座椅当前状态
message SeatStatus {
  int32 seat_id = 1;
  int32 current_x = 2;
  int32 current_y = 3;
  int32 current_recline = 4;
  bool is_occupied = 5;       // 是否有人
}

3.2.2 接口设计的“黄金法则”

语义清晰：接口名和字段名要自解释。别用 setData 这种，用 AdjustPosition 一目了然。
参数最小化：只传必要参数。能通过服务端推导的，就不要让客户端传。比如，座椅编号可以从上下文获取，就不需要每次都传。
返回值结构化：不要只返回一个 bool 或 int。返回一个结构体，包含状态码、错误信息、业务数据，方便调用方做异常处理。
考虑扩展性：字段编号留一些余量，方便后续增加字段而不破坏兼容性。

我的个人习惯： 每个接口都设计一个 RequestHeader 和 ResponseHeader，用来携带 traceId、时间戳、版本号等元信息。这在排查问题时特别有用。

3.3 服务契约与版本管理

接口定义好了，怎么保证服务提供者和消费者之间“说话算话”？这就是服务契约的作用。契约是双方共同遵守的约定，包括接口定义、数据类型、行为约束等。

但现实是，业务在变，接口也在变。怎么管理这种变化？版本管理就是答案。

3.3.1 契约的“三要素”

要素	说明	智舱示例
语法契约	接口名、参数类型、返回值结构	`AdjustPosition` 必须接收 `AdjustPositionRequest`
语义契约	接口的行为含义、前置条件、后置条件	调节座椅前，必须确保车辆处于“上电”状态
质量契约	响应时间、可用性、吞吐量	座椅调节指令的响应时间 < 100ms

3.3.2 版本管理策略

我推荐语义化版本控制（SemVer）：主版本号.次版本号.修订号。

主版本号：不兼容的变更。比如，删除了一个接口，或者修改了参数类型。
次版本号：向后兼容的新功能。比如，新增了一个接口，或者给现有消息增加了可选字段。
修订号：向后兼容的缺陷修复。比如，修复了一个bug，没有改变接口行为。

关键原则： 服务提供者必须同时支持多个版本，给消费者留出迁移时间。不要“一刀切”下线旧版本。

3.3.3 版本兼容性检查清单

新增字段：必须是 optional 或带默认值，不能是 required。
删除字段：禁止直接删除。标记为 deprecated，保留字段编号，等所有消费者迁移后再清理。
修改字段类型：禁止。这属于不兼容变更，必须升级主版本号。
新增接口：允许。不影响已有接口的消费者。
删除接口：禁止直接删除。先标记 deprecated，提供替代接口，再逐步下线。

我曾经犯过的错： 有一次，我直接删除了一个接口的某个字段，结果导致所有旧版本的HMI应用崩溃。从那以后，我严格执行“先标记废弃，再等待两个发布周期，最后才清理”的策略。

3.4 知识结构图：服务设计方法论全景

下面这张图，把服务粒度、接口设计、契约管理串在了一起。你可以把它当作本章的“思维导图”。

3.5 本章小结

服务设计没有银弹，但有章可循。记住三点：

粒度：用业务边界、复用潜力、变更频率去卡，别拍脑袋。
接口：用IDL（如Protobuf）定义，语义清晰、参数最小化、考虑扩展。
契约：语法、语义、质量三要素缺一不可，版本管理用SemVer，兼容性变更要谨慎。