1.2 什么是 API

这节要搞懂：API 是什么，为什么嵌入式开发离不开它。 需要基础：1.1

一、定义

API 是 应用程序编程接口（Application Programming Interface）的简称。它本质上是一套规则，定义了软件之间如何"对话"与协作，是数据与功能共享的桥梁。

换句话说：API 规定了"你能要什么、该怎么要、会得到什么"，但不告诉你它内部是怎么实现的。

二、打个比方：餐厅菜单

菜单就是餐厅给你的 API —— 一份约定好的清单，告诉你能点什么、怎么点，你不需要知道菜是怎么炒的。

餐厅里的	对应编程里的
菜单上的"宫保鸡丁"	函数名
点菜时说"要中辣"	传给函数的参数
端上来的那盘菜	函数的返回值
后厨怎么炒的	函数内部的实现（你不用管）

三、看一个真实的 API

esp_err_t gpio_set_level(gpio_num_t gpio_num, uint32_t level);

拆开看，任何一个 API 都是这三部分：

部分	这个例子里	含义
函数名	gpio_set_level	我要干什么：设置 GPIO 电平
参数	gpio_num、level	在哪干、干成什么样
返回值	esp_err_t	干成了没有

用的时候就一行：

gpio_set_level(2, 1);       // 让 2 号引脚输出高电平

至于芯片内部往哪个地址写了什么数字才把引脚拉高的？完全不需要知道。

四、为什么要有 API

第一，把复杂的东西藏起来。

gpio_set_level 内部可能有几十行代码，要处理不同芯片型号、不同引脚组的差异。但对你来说，它就是一行。

第二，换了实现，你的代码不用改。

只要"函数名、参数、返回值"这个约定不变，厂商在内部怎么优化都行，你的代码一个字都不用动。

五、返回值一定要看

ESP-IDF 里绝大多数 API 都返回 esp_err_t：

// ❌ 不管返回值：万一失败了，你根本不知道
gpio_set_level(2, 1);

// ✅ 判断一下
if (gpio_set_level(2, 1) != ESP_OK) {
    printf("set level failed\n");
}

// ✅ 或者用这个宏：出错就直接报错终止程序后重启，适合初始化阶段
ESP_ERROR_CHECK(gpio_config(&config));

ESP_ERROR_CHECK 什么时候用

初始化阶段用它（屏幕初始化失败了，程序继续跑也没意义，不如直接重启让你看到）。

运行阶段别用它（读一次传感器失败就重启整机，太粗暴了，应该重试）。

六、怎么查一个不认识的 API

看到没见过的函数名别慌，按这个顺序查：

1. 函数名猜个大概意思（i2c_master_transmit = I2C 主机发送）
2. 看参数：每个参数是什么、单位是什么
3. 看返回值：成功返回什么、失败有哪几种
4. 看官方文档的示例代码，照着改最快

学嵌入式的日常

你 90% 的时间就是在查 API、调 API。

看到一堆没见过的函数名不用背 —— 它们只是"菜单上的菜"，用到哪个查哪个。

本节要点

• API = 一套调用规则，规定能要什么、怎么要、得到什么
• 三个组成：函数名（干什么）、参数（怎么干）、返回值（成没成）
• 好处：藏起复杂度，而且换了内部实现你的代码不用改
• ⭐ 返回值一定要判断，初始化阶段可以用 ESP_ERROR_CHECK
• 不认识的 API 现查就行，不用背

动手试试

1. 用自己的话说清楚什么是 API。
2. 想一想生活中还有哪些"API"（提示：ATM 机的按钮、电视遥控器、快递柜）。
3. 打开 ESP-IDF 官方文档，找到 gpio_config 这个函数，说出它的参数是什么、返回值有哪几种。