第4章：AUTOSAR自适应平台架构文档：面向服务的架构（SOA）文档、Manifest文件编写规范
4.1 为什么SOA文档这么重要？
说实话，我刚接触AUTOSAR自适应平台那会儿，最头疼的就是SOA文档。你想想看，传统ECU开发，大家各写各的接口文档，能跑就行。但到了自适应平台，一切都不一样了。
面向服务的架构，说白了就是把功能拆成一个个服务。每个服务独立部署、独立升级。我参与的第一个自适应项目，就因为服务接口定义不清晰，导致集成阶段天天吵架。嗯，从那以后，我养成了一个习惯：先写文档，再写代码。
4.2 SOA文档的核心要素
我个人习惯把SOA文档分成三块：服务定义、接口规范、部署描述。这三块缺一不可。
4.2.1 服务定义
服务定义要回答三个问题：
- 服务做什么？ 一句话说清楚功能边界
- 服务依赖什么？ 需要哪些其他服务
- 服务提供什么？ 对外暴露的接口列表
我在项目中遇到过，有人把服务定义写成了一篇小论文。没必要！一个服务定义，三到五句话就够了。比如：
服务名称：VehicleSpeedService
功能描述：提供车辆当前速度信息，支持轮速和GPS两种来源
依赖服务：WheelSpeedService, GPSService
提供接口：GetCurrentSpeed(), SubscribeSpeedEvent()4.2.2 接口规范
接口规范是SOA文档的重头戏。这里我建议用表格来组织，清晰明了。
| 接口名称 | 方向 | 数据类型 | 说明 |
|---|---|---|---|
| GetCurrentSpeed | 请求/响应 | SpeedType | 返回当前车速，单位km/h |
| SubscribeSpeedEvent | 事件订阅 | SpeedEvent | 速度变化超过1km/h时触发 |
我的小技巧： 接口命名要统一。我习惯用"动词+名词"的格式，比如GetSpeed、SetMode。千万别一会儿用getSpeed，一会儿用SpeedGet，后期维护会疯掉。
4.3 Manifest文件编写规范
Manifest文件，说白了就是自适应平台的"身份证"。每个可执行文件、每个服务实例，都得配一个Manifest。我曾经见过一个项目，因为Manifest写错了，导致整个系统启动不起来。
4.3.1 Manifest文件结构
一个标准的Manifest文件包含以下部分：
<?xml version="1.0" encoding="UTF-8"?>
<manifest>
<!-- 基本信息 -->
<version>1.0.0</version>
<vendor>BlueOcean</vendor>
<!-- 执行依赖 -->
<execution>
<startup>on_demand</startup>
<priority>50</priority>
</execution>
<!-- 服务接口 -->
<provided_services>
<service>VehicleSpeedService</service>
</provided_services>
<!-- 资源需求 -->
<resource>
<memory>256KB</memory>
<cpu>5%</cpu>
</resource>
</manifest>4.3.2 常见坑点
避坑指南： 我曾经因为Manifest里的版本号写错了，导致OTA升级失败。版本号必须遵循语义化版本规范，主版本号、次版本号、修订号一个都不能少。
还有几个容易踩的坑：
- 服务名大小写： 自适应平台对大小写敏感，VehicleSpeedService和vehiclespeedservice是两回事
- 资源估算： 别把内存估得太紧，留20%余量是基本操作
- 启动顺序： 依赖的服务没启动，你的服务就别想跑起来
4.4 文档版本管理
你想想看，一个项目几十个服务，每个服务都有文档。没有版本管理，那就是灾难。我建议：
- 每个文档都要有版本号，和代码版本对应
- 修改记录要写清楚，谁改了、改了啥、为什么改
- 用Git管理文档，别用Word的修订模式
核心原则： 文档和代码要同步更新。我见过太多项目，代码改了三版，文档还是第一版。这种文档，还不如没有。
4.5 实战建议
最后，分享几个我踩过的坑：
- 别追求完美： 文档先写出来，再慢慢优化。空想一个月不如写一页
- 模板化： 建立团队统一的文档模板，减少格式争论
- 评审机制： 文档要评审，就像代码要review一样
嗯，SOA文档和Manifest文件，说白了就是让机器和人能互相理解。写好了，项目顺风顺水；写不好，后期全是坑。我这些年最大的体会就是：文档不是负担，是投资。