第四节：自定义接口实战——创建功能包、编写msg/srv/action文件、编译与测试

好，咱们直接动手。前面讲了接口的概念和ROS2的通信机制，现在该自己造轮子了。说实话，我最早学ROS2的时候，最头疼的就是自定义接口。官方教程翻来覆去就那几个例子，真到自己项目里，各种坑就冒出来了。今天咱们就把这事彻底捋清楚。

4.1 创建功能包——别小看这一步

创建功能包，听起来简单吧？但很多人一上来就踩坑。我见过不少新手直接在src目录下写msg文件，然后编译报错，一脸懵。

正确的做法是：接口定义必须放在独立的功能包里。为什么？因为其他包要依赖这个接口包，如果接口和节点混在一起，依赖关系会乱成一锅粥。

咱们用命令创建：

ros2 pkg create --build-type ament_cmake tutorial_interfaces

注意，这里用ament_cmake，不是Python。虽然Python包也能定义接口，但我个人习惯用CMake包来放接口，兼容性更好，尤其是后面要跨语言调用的时候。

创建完后，目录结构是这样的：

tutorial_interfaces/
├── CMakeLists.txt
├── msg/
├── srv/
├── action/
└── package.xml

嗯，msg、srv、action这三个文件夹默认没有，得自己建。我刚开始就忘了建，直接把文件扔根目录里，编译报错找了半天原因。

4.2 编写msg文件——定义你的数据结构

msg文件说白了就是定义消息的字段和类型。ROS2支持的基础类型包括int32、float64、string、bool这些，也支持嵌套其他msg。

举个例子，咱们定义一个自动驾驶中常用的"障碍物信息"消息：

# tutorial_interfaces/msg/Obstacle.msg
int32 id
string label
float64 x
float64 y
float64 z
float64 length
float64 width
float64 height
float64 velocity_x
float64 velocity_y
float64 yaw
uint8 confidence

这里有个小技巧：字段命名用蛇形命名法（snake_case），这是ROS2的惯例。我曾经见过有人用驼峰命名，结果编译没问题，但和其他包对接时各种不兼容。

再复杂一点，咱们可以定义嵌套消息。比如定义一个"障碍物列表"：

# tutorial_interfaces/msg/ObstacleArray.msg
tutorial_interfaces/Obstacle[] obstacles
builtin_interfaces/Time header_stamp
string frame_id

注意，引用自定义消息时，要写完整的包名+消息名。这个坑我踩过——少写了包名，编译报"找不到类型"的错误。

4.3 编写srv文件——请求与响应

srv文件比msg多了一个---分隔线，上面是请求，下面是响应。说白了，就是定义你问什么、我答什么。

咱们写一个"路径规划请求"的服务：

# tutorial_interfaces/srv/PlanPath.srv
# 请求
float64 start_x
float64 start_y
float64 goal_x
float64 goal_y
string algorithm  # 可选: "astar", "rrt", "hybrid"

---
# 响应
bool success
tutorial_interfaces/PathPoint[] path
float64 computation_time_ms
string error_message

这里PathPoint是另一个自定义消息，咱们可以提前定义好：

# tutorial_interfaces/msg/PathPoint.msg
float64 x
float64 y
float64 z
float64 yaw
float64 curvature
float64 speed_limit

你想想看，如果不用自定义消息，把路径点全塞进一个数组里，代码得多难看？接口设计得好，后面写节点的时候能省一半的精力。

4.4 编写action文件——长期任务

action文件比srv多了一个---，用来定义反馈。适合那些需要长时间执行的任务，比如"自动驾驶到目标点"。

咱们写一个"导航到目标"的action：

# tutorial_interfaces/action/NavigateToPose.action
# 目标
float64 target_x
float64 target_y
float64 target_yaw
---
# 结果
bool reached
float64 total_distance
float64 total_time_s
---
# 反馈
float64 current_x
float64 current_y
float64 current_yaw
float64 distance_remaining
float64 progress_percent

action文件的结构是：目标（goal）→ 反馈（feedback）→ 结果（result）。注意顺序不能乱，中间用---隔开。

我记得第一次写action文件时，把反馈和结果的顺序搞反了，编译没报错，但客户端一直收不到反馈，排查了半天才发现是顺序问题。

4.5 配置CMakeLists.txt和package.xml

文件写好了，但编译系统还不知道它们的存在。需要手动配置一下。

先看package.xml，要添加依赖：

<buildtool_depend>rosidl_default_generators</buildtool_depend>
<exec_depend>rosidl_default_runtime</exec_depend>
<member_of_group>rosidl_interface_packages</member_of_group>

再看CMakeLists.txt，关键配置如下：

find_package(rosidl_default_generators REQUIRED)

set(msg_files
  "msg/Obstacle.msg"
  "msg/ObstacleArray.msg"
  "msg/PathPoint.msg"
)

set(srv_files
  "srv/PlanPath.srv"
)

set(action_files
  "action/NavigateToPose.action"
)

rosidl_generate_interfaces(${PROJECT_NAME}
  ${msg_files}
  ${srv_files}
  ${action_files}
  DEPENDENCIES builtin_interfaces
)

ament_export_dependencies(rosidl_default_runtime)

这里有个容易忽略的点：DEPENDENCIES builtin_interfaces。如果你的msg里引用了builtin_interfaces/Time，就必须加上这个依赖，否则编译会报找不到头文件。

4.6 编译与测试——验证你的接口

配置好了，开始编译：

cd ~/ros2_ws
colcon build --packages-select tutorial_interfaces

编译成功后，记得source一下：

source install/setup.bash

怎么验证接口是否生成成功？用ros2 interface命令：

ros2 interface show tutorial_interfaces/msg/Obstacle
ros2 interface show tutorial_interfaces/srv/PlanPath
ros2 interface show tutorial_interfaces/action/NavigateToPose

如果能看到完整的字段定义，说明接口生成成功了。我习惯在编译后立刻跑一遍这个命令，确认无误再继续写节点代码。

还可以用ros2 interface list查看所有可用的接口，过滤一下：

ros2 interface list | grep tutorial_interfaces

4.7 避坑指南——我踩过的那些坑

4.8 知识体系总览

下面这张图展示了自定义接口的完整流程和核心逻辑：

4.9 实战小技巧

# Version: 1.2
# Date: 2024-03-15
# Author: Your Name
# Description: 障碍物信息，v1.2新增confidence字段

uint8 confidence 100  # 默认置信度100%

好了，自定义接口的完整流程就是这样。从创建包、写文件、配编译、到验证测试，每一步都有讲究。你按这个流程走一遍，基本不会出大问题。如果编译报错，先检查CMakeLists.txt里的文件路径对不对，再检查package.xml的依赖有没有加全——80%的编译问题都出在这两个地方。

可可精品资料库