企业官网建设流程全解析

第一次翻 STM32 标准外设库的源码，看到GPIO_Init(GPIOA, &GPIO_InitStructure)这种写法，十有八九的人心里都会冒出一句：直接GPIO_Init(GPIOA, PIN5, OUT, 50M)不就完了，为什么要先定义一个结构体，填一堆成员，再把地址传进去？更夸张的是定时器和串口，TIM_TimeBaseInit、UART_Init全都是一大包参数塞进一个结构体里。刚开始接触 STM32 的时候我也觉得这是库函数作者在"绕远路"，直到自己写过一个给同事用的驱动接口，被反复改签名改到崩溃，才明白结构体传参这件事根本不是风格问题，而是 C 语言在资源受限的芯片上，把接口做稳做久的最优解。这篇就围绕结构体、STM32、库函数、参数这几件事，把"为什么是一大包"从编译器、ABI、工程维护三个层面拆开讲清楚，顺带把初始化、调试查看、踩坑排查这些实操细节一并说透，不管你是刚开始点灯的新手，还是已经在写自己驱动库的老手，都能从里面拿到能直接抄的东西。

1. 一个"啰嗦"的初始化函数，暴露了 C 语言传参的真实成本

1.1 从 GPIO 的两种写法说起

假设我们不用库，直接把寄存器写一遍：

RCC->APB2ENR |= 1 << 2; // 开 GPIOA 时钟 GPIOA->CRL &= ~(0xF << 20); // 清 PA5 配置位 GPIOA->CRL |= (0x1 << 20); // 推挽输出 10MHz GPIOA->ODR |= 1 << 5; // 输出高

这段代码短，但它把"引脚编号、模式、速度、时钟"四件事硬编码进了位运算里。换成库函数版本：

GPIO_InitTypeDef GPIO_InitStructure; GPIO_InitStructure.GPIO_Pin = GPIO_Pin_5; GPIO_InitStructure.GPIO_Mode = GPIO_Mode_Out_PP; GPIO_InitStructure.GPIO_Speed = GPIO_Speed_50MHz; GPIO_Init(GPIOA, &GPIO_InitStructure);

多出来七八行，但读代码的人一眼就能看出"PA5 是推挽输出、50MHz"，不需要在脑子里把0x1 << 20翻译一遍。这是第一层价值：参数携带了名字。

真正有意思的是第二层。库函数为什么不写成GPIO_Init(GPIOA, GPIO_Pin_5, GPIO_Mode_Out_PP, GPIO_Speed_50MHz)？毕竟四个参数而已，写在函数签名里不是更直观吗？答案在编译器和架构层面。

1.2 ARM 架构下参数是怎么传进函数的

STM32 用的是 ARM Cortex-M 内核，函数调用遵循 AAPCS（ARM Architecture Procedure Call Standard）约定。这个约定里有一条关键规则：前四个字（word）的参数放在 r0 到 r3 寄存器里，超出的部分压到栈上。

也就是说，如果你写一个 4 参数的函数，编译器生成的是纯寄存器操作，没有栈的读写，快得几乎无感。看起来GPIO_Init用 4 个直接参数完全没有性能问题。但问题在于，这个函数一旦上线，签名就冻结了，后面想加参数就是灾难。

还有个更隐蔽的点：结构体按值传参在 AAPCS 下并不等于"逐成员塞寄存器"。当一个结构体大于 4 字节时，调用者会在自己的栈帧（或调用者分配的临时空间）里复制出一份完整副本，然后把这份副本的地址放到 r0 传进去。也就是说，void f(GPIO_InitTypeDef s)这种写法，表面上是"按值传递"，实际上底层是一次memcpy加一个指针。而 STM32 官方库函数用的都是void GPIO_Init(GPIO_TypeDef* GPIOx, GPIO_InitTypeDef* GPIO_InitStruct)，传的是指针，连那份拷贝都省了。

这就是为什么库函数看起来"多此一举"地用结构体指针：它同时拿到了可扩展性和零拷贝开销，代价只是调用者要自己声明一个结构体变量。这笔账，在嵌入式场景里怎么算都划算。

1.3 指针参数还顺手解决了一个语义问题

C 语言里函数参数默认是"值传递"，函数内部改不了调用者的变量。但嵌入式驱动经常需要干两件事：一是把配置读进来，二是把结果写回去。比如：

void RTC_GetTime(RTC_TimeTypeDef* RTC_TimeStruct); // 出参 void GPIO_Init(GPIO_TypeDef* GPIOx, GPIO_InitTypeDef* GPIO_InitStruct); // 入参

靠指针，一个函数能同时返回多个值，不需要定义全局变量，也不需要返回一个巨大的结构体副本。如果改成返回值形式：

RTC_TimeTypeDef RTC_GetTime(void);

在 AAPCS 下，返回一个大于 4 字节的结构体，编译器会偷偷在函数签名里加一个隐藏的第一参数（通常叫 sret，structure return pointer），把返回值的地址传进去，语义上变成一个void函数。可读性反而变差了，还容易让新手以为"返回的是值，随便改"。

有一点值得单独强调：入参最好加const。像void Flash_Program(const uint8_t* buf, uint32_t len)这种，一眼就知道函数不会动你的缓冲区；不加 const 的指针参数，读代码的人就得去翻实现，看它到底会不会写回。STM32 里GPIO_Init的结构体参数没有 const，是因为历史原因，你自己写库的时候完全应该加上。

2. 结构体作为"配置包"：库函数设计者在解决什么问题

2.1 参数列表的膨胀曲线和版本兼容的噩梦

我做过一个真实的对比。给一块板子写电机驱动接口，第一版是这样：

void Motor_Init(uint8_t id, uint16_t pwm_freq, uint8_t dir, uint8_t brake);

到第三版功能加完：

void Motor_Init(uint8_t id, uint16_t pwm_freq, uint8_t dir, uint8_t brake, uint16_t dead_time, uint8_t current_limit, uint8_t microstep, uint16_t accel);

八个参数。这时候问题来了：所有调用点都得改，而且参数顺序一旦记错，dead_time和accel传反了，编译器不会报错——两个都是uint16_t，它会安安静静地把电流限制当加速度用，烧掉的可能是驱动板。这种 bug 在项目后期出现，排查成本极高。

改成结构体之后：

typedef struct { uint8_t id; uint16_t pwm_freq; uint8_t dir; uint8_t brake; uint16_t dead_time; uint8_t current_limit; uint8_t microstep; uint16_t accel; } Motor_Config_t; void Motor_Init(const Motor_Config_t* cfg);

后面再加一个uint8_t invert，只要在结构体尾部追加字段，老调用点一行都不用动（前提是配好默认值，下面会讲）。这就是库函数"接收一大包参数"最核心的动机：用数据结构的演化，替代函数签名的演化。STM32 的 HAL 库从 F1 演进到 F4、H7，GPIO_InitTypeDef的字段一直在加（比如增加GPIO_Alternate用于复用功能），但HAL_GPIO_Init的签名十几年没变过。

2.2 默认值、可选字段与"我只想改一个参数"

结构体还有个隐藏福利：它让"默认配置"这件事变得可以表达。看 SPI 初始化的例子：

SPI_HandleTypeDef hspi1 = {0}; hspi1.Instance = SPI1; hspi1.Init.Mode = SPI_MODE_MASTER; hspi1.Init.Direction = SPI_DIRECTION_2LINES; hspi1.Init.DataSize = SPI_DATASIZE_8BIT; hspi1.Init.CLKPolarity = SPI_POLARITY_LOW; hspi1.Init.CLKPhase = SPI_PHASE_1EDGE; hspi1.Init.NSS = SPI_NSS_SOFT; hspi1.Init.BaudRatePrescaler = SPI_BAUDRATEPRESCALER_256; hspi1.Init.FirstBit = SPI_FIRSTBIT_MSB; hspi1.Init.TIMode = SPI_TIMODE_DISABLE; hspi1.Init.CRCCalculation = SPI_CRCCALCULATION_DISABLE; hspi1.Init.CRCPolynomial = 10;

十几个字段，看起来很啰嗦。但如果你想做一个"标准 SPI 主机"，大部分字段都是固定值，你只需要复制一份模板，改动Instance和BaudRatePrescaler两个字段就完事了。这在工程上叫"模板化配置"，比记住一个十五参数的函数签名容易太多。

如果换成直接传参，函数原型大概长这样：

HAL_SPI_Init(SPI1, MASTER, 2LINES, 8BIT, LOW, 1EDGE, SOFT, 256, MSB, DISABLE, DISABLE, 10);

调用点一眼看过去，谁都不知道第几个参数是极性、第几个是相位。而结构体版本，字段名本身就是文档。

2.3 字段名即命名空间，避免参数顺序错误

我总结过一条经验：参数类型相同且个数超过三个的函数，几乎一定会被传错。uint16_t连着来两个，编译器帮不了你。结构体版本虽然也可能填错字段，但至少要求你写出字段名：

cfg.dead_time = 100; // 写错字段名，编译不过 cfg.accel = 2000;

这种"错误只能发生在语义层，不能发生在位置层"的特性，是结构体传参在团队协作里最大的价值。代码评审的时候，看字段名就能判断对错；看一长串裸参数，只能靠人肉对照函数原型。

顺便提一个常被忽略的点：结构体字段的顺序本身也携带信息。我习惯把"必须设置"的字段放前面，"可选/有默认值"的字段放后面，再配合注释：

typedef struct { uint32_t baud; /* 必填 */ uint8_t data_bits; /* 必填 */ uint8_t stop_bits; /* 必填 */ /* ---- 以下有默认值，可保持 0 ---- */ uint8_t invert; uint8_t flow_ctrl; } Uart_Cfg_t;

这样别人接手时，扫一眼就知道哪些不能空着。

3. 拆开一个真实的配置结构体：每个字段都在说什么

3.1 GPIO_InitTypeDef 逐字段对照

标准库的GPIO_InitTypeDef只有四个字段，是全库最简单的一个，正好拿来当解剖样本：

这里有个容易误解的地方：GPIO_Speed不是"引脚翻转速度"，而是输出驱动电路的压摆率档位。50MHz 档意味着边沿更陡、EMI 更大、功耗更高。我曾经在一个做温湿度采集的板子上，把所有引脚都设成 50MHz，结果 ADC 采样值一直跳。后来把非高速信号（比如 LCD 的 RS 引脚）改成 2MHz，噪声立刻小了。这就是"库函数里一个字段看着无关紧要，实际影响硬件行为"的典型例子。

还有一点：GPIO_Mode这个字段其实是把"方向"和"上下拉/复用"两件事打包了。如果没配置外部上拉，又选了GPIO_Mode_IN_FLOATING，引脚悬空时读进来的是随机值。新手最常踩的坑之一就是按键输入读了半天没反应，最后发现是模式选错。

3.2 定时器：TIM_TimeBaseInitTypeDef 与溢出时间怎么算

定时器的配置结构体字段更多，也更能体现"为什么需要一整包"：

TIM_TimeBaseInitTypeDef TIM_TimeBaseStructure; TIM_TimeBaseStructure.TIM_Prescaler = 71; // 预分频 TIM_TimeBaseStructure.TIM_Period = 999; // 自动重装载值 TIM_TimeBaseStructure.TIM_ClockDivision = 0; TIM_TimeBaseStructure.TIM_CounterMode = TIM_CounterMode_Up; TIM_TimeBaseStructure.TIM_RepetitionCounter = 0; TIM_TimeBaseInit(TIM3, &TIM_TimeBaseStructure);

溢出时间的计算公式是：

T = (TIM_Prescaler + 1) × (TIM_Period + 1) / TIMxCLK

假设 TIM3 挂在 APB1 上，时钟经过倍频后是 72MHz，代入上面的值：

T = (71 + 1) × (999 + 1) / 72,000,000 = 72 × 1000 / 72e6 = 1ms

正好 1ms 一次中断。这里要注意两个"加一"：预分频器是除法器，写入 N 意味着分频系数是 N+1；自动重装寄存器同理，计到 ARR 值再回零，一共 ARR+1 个计数。这个细节在 F1/F4 的参考手册里有图，但很多人第一次配定时器时只记住了"PSC 和 ARR 填数就行"，导致算出来的时间总是差一个周期。

如果用直接传参的写法，TIM_TimeBaseInit(TIM3, 71, 999, 0, 0, 0)——后面三个连续的 0 是什么？没人记得住。这就是结构体自解释的价值。

再补一个实战经验：把PSC和ARR分散成"一个粗调、一个精调"是常见做法。比如需要 1ms 中断，可以配成 PSC=7199、ARR=9，也可以配成 PSC=71、ARR=999。前者分频大、计数范围小，后者分辨率高。一般来说，分辨率要求高（比如做 PWM 微调）就让 ARR 大一点，因为 ARR 决定了 PWM 的占空比调节精度；对纯定时中断来说两者等价。

3.3 串口：波特率字段背后的分频计算

HAL 的串口结构体里，BaudRate是唯一一个不直接对应寄存器的字段：

huart1.Instance = USART1; huart1.Init.BaudRate = 115200; huart1.Init.WordLength = UART_WORDLENGTH_8B; huart1.Init.StopBits = UART_STOPBITS_1; huart1.Init.Parity = UART_PARITY_NONE; huart1.Init.Mode = UART_MODE_TX_RX; huart1.Init.HwFlowCtl = UART_HWCONTROL_NONE; huart1.Init.OverSampling = UART_OVERSAMPLING_16;

HAL 内部会拿BaudRate去算USARTDIV，再写进BRR寄存器。以 USART1 挂 APB2、时钟 72MHz、16 倍过采样为例：

USARTDIV = 72,000,000 / (16 × 115200) = 39.0625

整数部分 39，小数部分 0.0625 × 16 = 1，所以BRR = (39 << 4) | 1 = 625 = 0x271。

这就是"结构体里的值是工程单位，寄存器里的是硬件单位"的分层设计。库函数在中间做了换算，让上层代码永远只说"115200"这种人类能理解的值。如果库函数直接要求你传0x271，那每换一次主频你都得重新算一遍。

提示：如果发现串口乱码，先确认 APB 时钟是不是你以为的那个值。F1 系列 APB1 最大 36MHz，但定时器会额外倍频；F4 系列 APB1 是 42MHz。主频配错的时候，BRR 算出来的波特率就偏了，现象是偶尔能收到、错字率高，很容易被误判成硬件问题。

4. 结构体初始化的三种写法与它们的真实差异

4.1 memset、= {0}和逐个赋值

结构体定义在栈上，里面的值是随机的。这个"随机"不是理论问题，我见过因为没初始化导致 PWM 输出异常、串口配置成 9 位数据位、看门狗莫名复位的真实案例。初始化方式主要有四种：

我更推荐= {0}加逐个赋值的组合：

GPIO_InitTypeDef gpio = {0}; gpio.GPIO_Pin = GPIO_Pin_5; gpio.GPIO_Mode = GPIO_Mode_Out_PP; gpio.GPIO_Speed = GPIO_Speed_2MHz;

先整体清零，再只改需要的字段。这样一个好处是：结构体以后新增字段时，老代码不会因为新字段是垃圾值而行为突变。库函数内部的assert_param校验也才有意义——如果不是零值，很多断言根本拦不住。

4.2 不初始化会怎样：一个偶发死机的案例

说一个我自己踩过的坑。写了一个 OLED 刷屏的驱动，函数长这样：

void OLED_DrawLine(Point_t a, Point_t b);

Point_t只有x、y两个uint8_t。调用的时候我图省事，写成了：

Point_t p; p.x = 10; OLED_DrawLine(p, p2); // p.y 没赋值

编译通过，大部分时候也正常——因为栈上的残留值是上一次调用留下的y=20。直到某次在中断里调用了这个函数，栈布局变了，p.y变成了 255，OLED_DrawLine内部算地址时越界，直接 HardFault。这种 bug 的恶心之处在于：它跟代码逻辑无关，只跟栈的历史状态有关，加打印可能就消失了（打印改变了栈布局），属于典型的"海森堡 bug"。

从那以后我定了个规矩：栈上声明的结构体，第一行必须是= {0}或memset，没有例外。这一条规则后来帮我省掉了无数次排查。

4.3 位域与枚举赋值时的隐形陷阱

结构体里如果包含位域，还有一个更隐蔽的问题：

typedef struct { uint8_t enable : 1; uint8_t mode : 3; uint8_t : 4; // 填充 } Ctrl_t;

位域的赋值不能超出位宽。ctrl.mode = 9;在 3 位位域里只会保留低 3 位，结果是 1，编译器可能只给一个警告甚至不报错。我在一次协议解析里就被这个坑过：上层传进来的模式值本该是 0~7，结果传了个 8，被截断成 0，设备切到了完全错误的模式，日志上看一切正常。

另外，位域的内存布局依赖编译器和字节序。把结构体直接memcpy到通信缓冲区发出去，如果两端编译器不同（比如一端是 Keil AC5、另一端是 GCC），位域顺序可能相反。这种场景我建议老老实实按字节手工打包，别依赖位域，除非你确定两端工具链一致。

注意：#pragma pack(1)能消除结构体填充，让sizeof等于成员之和，在协议编解码里很有用。但它会带来非对齐访问，Cortex-M 部分指令对非对齐地址访问会直接 HardFault（M0 内核尤其严格）。如果只是本地传参，不要加 pack(1)，让编译器按自然对齐排布效率最高。

5. 在 Keil 里把结构体看穿：调试窗口的正确用法

5.1 Watch 窗口展开结构体成员

写 STM32 代码最常用的调试手段就是打断点看变量，但结构体在 Keil 里的查看方式有点讲究。假设有个全局变量GPIO_InitTypeDef GPIO_InitStructure;，在 Debug 模式下：

1. 进入 Debug（Ctrl+F5），打开 View → Watch Windows → Watch 1；
2. 在 Watch 窗口的<Enter expression>行输入变量名GPIO_InitStructure，回车；
3. 变量左侧会出现一个+，点开就能看到GPIO_Pin、GPIO_Mode、GPIO_Speed各自的数值；
4. 想看十六进制，右键该行 → Number Base → Hexadecimal 切换。

有几个坑必须说清楚。第一，结构体是局部变量时，只有运行到它所在的作用域内才看得到值，否则窗口里会显示cannot evaluate。很多人断点打错位置，以为变量丢了，其实是作用域不对。第二，Watch 窗口默认是断点触发时才刷新，想让它实时刷新，需要打开 View → Periodic Window Update，但这会拖慢调试速度，一般不推荐常开。第三，指针型变量默认只显示地址，想直接看指向内容，要在表达式里写*ptr，或者展开指针节点。

还有一个很多人不知道的小技巧：Keil 的 Command 窗口可以直接执行表达式。比如想快速看某个寄存器的值，输入：

>GPIOA->ODR

回车就出结果。想在某个变量变化时自动停下来，可以在 Watch 窗口右键选 Set Access Breakpoint，比手动打断点高效得多。

5.2 优化等级把变量"弄丢"了怎么办

一个高频困惑：明明定义了变量，Watch 窗口里却显示<not in scope>或者优化掉了。原因通常是编译器把局部变量优化进寄存器，或者干脆删掉了。解决方案有两条：

• 调低优化等级。Debug 配置里改成-O0（AC5 是 Level 0，AC6 是-O0），变量就会规规矩矩待在栈上；
• 给变量加volatile。特别是那些在中断和主循环之间共享的结构体，不加 volatile，编译器可能把读操作缓存起来，导致你在调试器里看到的值跟实际硬件状态不一致。

我个人的习惯是：Debug 用-O0，Release 用-Os，两者都跑一遍。曾经遇到过一个只在-Os下复现的问题——因为优化后某个循环变量的自增被合并了，导致超时判断永远不成立。这种问题如果只在-O0下测试，是发现不了的。

5.3 没有调试器时的土办法：串口打印结构体

有些量产板子没留 SWD 接口，或者现场调试只能用串口，这时候写一个通用的打印函数非常值：

#include <stdio.h> void dump_gpio_cfg(const GPIO_InitTypeDef* cfg) { printf("pin=0x%04X mode=0x%02X speed=0x%02X\r\n", cfg->GPIO_Pin, cfg->GPIO_Mode, cfg->GPIO_Speed); }

注意重定向printf的时候，fputc要选对串口，并且不要在高频中断里调用，printf内部有较长的处理链路，会打乱时序。我一般只在初始化阶段和出错分支里打印。

对于大型结构体，写一个遍历打印的宏会更省事：

#define DUMP_U32(s, f) printf(" %-16s = %lu\r\n", #f, (unsigned long)((s)->f))

配合DUMP_U32(&cfg, baud);这种调用，输出对齐整齐，出问题的时候一眼就能看出哪个字段不对。

6. 结构体传参踩过的坑：一次完整排查链路

6.1 现象：改了结构体成员，硬件没反应

那次的问题很典型。我用标准库配 TIM4 做 PWM 输出，代码大概是这样：

TIM_TimeBaseInitTypeDef base; TIM_OCInitTypeDef oc; TIM_TimeBaseStructInit(&base); base.TIM_Prescaler = 71; base.TIM_Period = 999; TIM_TimeBaseInit(TIM4, &base); TIM_OCStructInit(&oc); oc.TIM_OCMode = TIM_OCMode_PWM1; oc.TIM_OutputState = TIM_OutputState_Enable; oc.TIM_Pulse = 500; TIM_OC1Init(TIM4, &oc); TIM_Cmd(TIM4, ENABLE);

现象是：示波器上一点波形都没有，PA6（TIM4_CH1）一直是低电平。改了TIM_Pulse也没变化。

6.2 逐步缩小范围：从时钟到寄存器

我的排查顺序是这样，你也可以照这个链路走：

第一步，确认时钟。TIM4 挂在 APB1 上，检查RCC_APB1PeriphClockCmd(RCC_APB1Periph_TIM4, ENABLE);有没有调用，以及 GPIOA 的时钟有没有开。这一步最容易被忽略，因为漏了时钟不会报错，只是外设完全没反应。

第二步，确认引脚复用。PA6 要配成复用推挽输出GPIO_Mode_AF_PP，而不是普通推挽。我当时用的是GPIO_Mode_Out_PP，这条就是隐患之一。

第三步，看寄存器。在调试器里直接展开TIM4->CR1、TIM4->CCER、TIM4->CCMR1、TIM4->ARR、TIM4->CCR1，逐个对照参考手册。这里我发现了关键线索：TIM4->CCR1的值确实是 500，CCER的 CC1E 位也是 1，说明定时器和输出比较通道都配好了，问题不在 PWM 逻辑上。

第四步，回到 GPIO。展开GPIOA->CRL，发现 PA6 的配置位是"通用推挽输出"，而不是"复用推挽输出"。到这一步基本就定案了：定时器在内部生成了 PWM，但引脚没有把定时器的输出信号引出来。

6.3 根因定位与修复验证

根因就是GPIO_Mode选错。改成GPIO_Mode_AF_PP，同时把GPIO_Speed设成 50MHz（PWM 频率稍高时低速档边沿会变缓），重新编译，示波器上立刻出现 1kHz、50% 占空比的方波。

修完我复盘了一下，为什么当初会写错：因为标准库的GPIO_InitTypeDef里，GPIO_Mode这个字段把"方向"和"复用"揉在了一起，命名是GPIO_Mode_AF_PP，一眼看过去和GPIO_Mode_Out_PP很像，加上我用的是TIM_OCStructInit给定时器结构体填默认值，却没有给 GPIO 结构体做类似的初始化，手写的时候脑子一滑就选了通用输出。

这件事之后我养成了两个习惯：一是所有外设结构体都先用XXXStructInit()或= {0}打底；二是在驱动里加一层校验函数，把明显的组合错误在初始化阶段就报出来。

6.4 类似的坑：中断共享结构体、指针悬空、跨文件类型不一致

顺着这个思路，我把这些年遇到的结构体相关坑整理成一张表，方便对照排查：

其中"跨文件类型不一致"这个问题最隐蔽。它的典型场景是：你把一个结构体定义在driver.h里，另一个同事在自己的模块里"图方便"重新抄了一份一模一样的定义，后来你加了一个字段，他那份没同步，两边sizeof就差了几个字节。传参的时候，函数按大结构体解读，实际传进来的内存不够，读出垃圾数据。解决办法只有一个：结构体定义只能有一处，所有人 include 同一个头文件，头文件加 include guard，不要复制粘贴。

还有"参数不足，期待是 1"这类编译错误，多数情况就是头文件和实现不同步。我之前遇到过一个人把函数原型从void f(void)改成了void f(int mode)，改了.c没改.h，结果调用点全都报这个错。看到这个报错，第一反应应该是去比对声明和定义，而不是去数参数个数。

7. 什么时候该用结构体传参，什么时候别用

7.1 判断标准：参数个数、类型组合、变化频率

结构体不是万能的。我给自己定了几个判断条件，供你参考：

• 参数 ≤ 3 个，且类型各不相同（比如void delay_ms(uint32_t ms)）：直接传，别包结构体，包了反而绕；
• 参数 ≥ 4 个，或者存在多个同类型参数（两个uint16_t连着）：用结构体，避免顺序错；
• 接口预期会长期演进、要给别人用：用结构体，并预留扩展空间；
• 需要返回多个值：用结构体指针做出参，或者定义Result_t结构体返回；
• 中断服务函数、高频采样回调里：慎用，见下一节。

还有一条经验：只在"配置"场景用结构体，不在"计算"场景用。配置是一次性的、字段多的、需要自解释的；计算是高频的、参数少的、追求指令数的。把两者混在一起，就会出现"为了算一个加法还要构造结构体"的荒唐代码。

7.2 中断和高频路径里的结构体拷贝代价

结构体按值传参在 AAPCS 下有一次隐式拷贝，拷贝成本正比于sizeof。假设一个结构体 64 字节，在 1kHz 的中断里按值传给一个函数，每秒就是 64KB 的内存拷贝——对 72MHz 的 M3 来说不算致命，但如果是个 2kHz 的电流环，加上浮点成员和嵌套结构体，累积起来就很可观了。

更麻烦的是栈。按值传参在栈上复制一份，如果中断嵌套两层，每层都这么干，栈压力会明显上升。STM32 默认栈大小往往只有 1KB，一不留神就溢出了，现象是随机 HardFault，极难定位。

所以高频路径里我坚持两条：

• 传指针，加const，绝不按值传大结构体；
• 结构体成员尽量用整型，避免double、避免嵌套大数组。如果必须放数组，考虑改成指针加长度两个字段。

/* 好：传指针，零拷贝 */ void Adc_Process(const Adc_Sample_t* sample); /* 差：64 字节按值传，每次调用都拷一份 */ void Adc_Process(Adc_Sample_t sample);

7.3 自己写库的一点进阶：结构体当对象 + 回调上下文

结构体传参玩到后面，会自然滑向"用 C 写面向对象"。STM32 HAL 里到处都是这种痕迹，比如UART_HandleTypeDef里既放配置（Init），又放运行时状态（RxState），还放回调函数指针。这是把结构体当成"对象"来用：

typedef struct { UART_TypeDef* instance; /* 依赖的硬件资源 */ Uart_Cfg_t cfg; /* 配置包 */ uint8_t* rx_buf; /* 运行时缓冲 */ uint16_t rx_len; void (*on_rx_done)(void* ctx, uint16_t len); /* 回调 */ void* ctx; /* 回调上下文，关键 */ } Uart_Drv_t;

这里ctx这个字段值得单独说。C 语言没有闭包，回调函数拿不到外部环境，只能靠一个void*把上下文传回去。很多新手写回调时用全局变量存状态，一旦有两个串口实例就乱套了。加上ctx，每个实例的回调都能拿到自己的数据，代码立刻从"一份"变成"可复用的 N 份"。这个模式和 STM32 的HAL_UART_RxCpltCallback系列是一个思路，只是 HAL 用的是全局 handle 变量，可复用性差一些。

再进一步，可以把函数指针也塞进结构体，做成虚表：

typedef struct Uart_Drv { int (*init)(struct Uart_Drv* self, const Uart_Cfg_t* cfg); int (*send)(struct Uart_Drv* self, const uint8_t* buf, uint16_t len); void (*deinit)(struct Uart_Drv* self); } Uart_Drv_t;

这样上层只依赖Uart_Drv_t，底层换成本地串口、DMA 串口、甚至虚拟串口，上层代码一行都不用改。这套写法在 Linux 内核里非常常见，在 MCU 上也完全跑得动，代价只是每个实例多几个字节的函数指针。

我个人在实际项目中用的最多的还是前一种：结构体只放配置和状态，函数用普通函数接收结构体指针。原因很实在——如果只是给一块板子写驱动，没必要为将来可能根本不存在的"多硬件适配"提前付出复杂度。什么时候真的出现了第二个实现（比如从 UART 换成 SPI），再抽虚表不迟，那时候你才知道接口该怎么切才不别扭。

最后再分享一个小技巧：给自己的配置结构体配一个XXX_Default()函数，专门用来填默认值，比在每个调用点写一堆赋值干净得多：

void Uart_Cfg_Default(Uart_Cfg_t* cfg) { memset(cfg, 0, sizeof(*cfg)); cfg->baud = 115200; cfg->data_bits = 8; cfg->stop_bits = 1; cfg->parity = 0; }

调用点就变成两行：先取默认，再改需要改的字段。库函数里那些XXXStructInit干的就是这件事，只是很多人不知道它的存在，宁可手写十几行赋值。这个函数一旦写好，整个项目里所有串口的默认配置就统一了，以后改默认波特率也只需要改一个地方，比你一个一个文件去搜要靠谱得多。