{
  "id": "foreign-function-interface",
  "title": "外部函数接口",
  "lang": "zh-Hans",
  "source_lang": "en",
  "summary": "外部函数接口使一种编程语言编写的代码能够调用另一种语言实现的函数，并协调调用约定、数据表示和运行时行为的差异。",
  "category": "computer-science",
  "subcategory": "software",
  "type": "concept",
  "aliases": [
    "FFI",
    "外来函数接口"
  ],
  "generated_at": "2026-11-05",
  "model": "pro/gpt-6.1-sol",
  "url": "https://aiwiki.page/zh/foreign-function-interface/",
  "translations": {
    "en": {
      "url": "https://aiwiki.page/en/foreign-function-interface/",
      "json": "https://aiwiki.page/en/foreign-function-interface.json"
    }
  },
  "sections": [
    {
      "heading": "",
      "text": "外部函数接口（foreign function interface，FFI）是一种机制，允许用一种编程语言编写的程序调用另一种语言实现的函数或使用其提供的服务。它通过协调函数调用、数据表示、内存管理和运行时行为方面的差异，实现跨语言的互操作性。一种常见用途是让高级语言调用通过C编程语言调用接口提供的库，但 FFI 并不限于 C。"
    },
    {
      "heading": "范围与相关接口",
      "text": "FFI 连接不同的语言环境，而应用程序编程接口（API）描述软件向使用者提供的操作。一个库可以提供 C API，并通过各自独立的绑定，让 Python、Java 或其他语言也能使用相同的操作。这些绑定内部可能依赖 FFI。\n\n应用二进制接口（ABI）规定了独立编译的组件必须遵循的底层约定，包括参数传递、返回值、寄存器使用以及数据布局的某些方面。FFI 通常使用现有的 ABI，但也会处理仅靠 ABI 无法解决的语言层面差异，例如字符串转换或对象生命周期跟踪。\n\nFFI 调用通常发生在同一个进程内，参与调用的组件共享同一地址空间。这使其有别于跨越进程边界的进程间通信和远程服务调用。一些互操作系统会结合这些方式，但 FFI 本身并不是网络协议或消息传递协议。\n\n“外部”是相对于发起调用的语言或运行时而言的，并不意味着被调用的函数在另一台计算机上运行，或来自外部组织。"
    },
    {
      "heading": "FFI 的工作原理",
      "text": "一次典型的外部函数调用包含以下几个步骤：\n\n- 描述函数。 调用方提供或获取一份声明，指定函数名称、参数类型、返回类型和调用约定。\n- 定位实现。 在链接时解析函数，或从运行时加载的库中获取函数。\n- 准备参数。 对值进行转换、复制，或将其表示为被调用函数能够理解的形式。\n- 执行调用。 由编译器生成的代码或运行时辅助程序按照目标 ABI 转移控制权。\n- 处理结果。 将返回值、错误信息以及任何移交的资源转换为符合调用方约定的形式。\n\n一些 FFI 在编译时就完成了其中的大部分工作，另一些则在运行时解释函数描述。当相关类型和约定已知时，编译器可以生成直接的原生调用；而解释器或运行时库则可能动态构造调用。\n\n调用约定与二进制兼容性\n\n调用约定决定了哪些参数放入寄存器、哪些参数放入调用栈，以及如何传递返回值等细节。即使函数名称已成功解析，调用约定不匹配仍可能导致错误结果或内存损坏。\n\n数据布局同样重要。整数的位宽、结构体的对齐方式以及布尔值的表示形式，都可能因语言或平台而异。结构体填充以及聚合类型的参数传递或返回规则必须符合 ABI。\n\nC 经常被用作语言间的互操作边界，因为它的接口可以用相对简单的函数、标量值、指针和结构体来表达，而且兼容 C 的工具链广泛可用。但这并不意味着 C ABI 是通用的：不同处理器架构、操作系统和工具链采用的约定可能不同。\n\nC++ 的互操作往往更复杂，原因包括名称修饰、类、模板、异常以及编译器特有的二进制约定。一种常见做法是在 C++ 功能外封装一层兼容 C 的接口。这种封装提供了更简单的交互边界，但并不会使 C++ 对象的表示形式变得可移植。\n\n数据转换与编组\n\n为跨接口传递数据而准备值的过程，通常称为编组。有些值可以直接传递，另一些则需要进行大量转换。\n\n常见问题包括：\n\n- 数值： 整数位宽、符号性、浮点格式和转换行为必须一致。\n- 字符串： 语言层面的字符串可能需要转换为以空字符结尾的字节序列，或转换为附带长度的指针。支持 Unicode统一码 本身并不意味着双方采用相同的编码。\n- 数组： 接口必须明确元素类型、长度、布局，以及被调用方是否可以修改或保留其存储空间。\n- 记录： 字段的顺序、大小、对齐方式和填充必须匹配。\n- 对象： 由运行时管理的对象可能需要以不透明句柄表示，而不是直接暴露。\n- 指针： 只有当指向的目标仍然有效，且接收代码理解其所指内容时，地址才有用。\n\n因此，FFI 不仅衔接二进制层面的差异，也衔接语义层面的差异。例如，指向字节的指针本身并不能说明这些字节是否表示文本、使用何种编码，或内存归谁所有。"
    },
    {
      "heading": "内存管理与运行时交互",
      "text": "所有权与生命周期\n\nFFI 契约最重要的内容之一，是明确每项资源归谁所有，以及何时可以释放。由外部库分配的内存，可能必须通过该库自身的释放函数来释放，而不能使用调用方的分配器。\n\n采用垃圾回收的托管运行时还会带来额外要求。回收器可能需要知道外部代码仍然持有某个对象的引用。如果回收器能够移动对象，FFI 可能会将对象固定在原位、复制其内容，或提供稳定的句柄而不是原始地址。\n\n所有权处理错误可能导致内存泄漏、重复释放或释放后使用错误。仅靠函数声明通常不足以传达所有必要的生命周期规则；这些规则往往写在文档或绑定注解中。\n\n回调与重入\n\n回调允许外部代码调用由调用方提供的函数。例如，原生库可以调用用另一种语言实现的比较函数。\n\nFFI 可以构造一个小型适配器，有时称为跳板（trampoline），用于接收原生调用并进入目标运行时。只要外部库仍有可能调用回调，回调对象及其关联状态就必须保持存活。\n\n回调还会带来重入：先前的外部调用尚未结束时，外部代码就可能再次调用进入运行时。这会影响锁的使用、运行时状态，以及原始调用之前所作假设的有效性。\n\n线程与阻塞操作\n\n外部库可能创建线程，或在宿主运行时并不知晓的线程上执行回调。某些运行时要求这些线程先接入运行时或完成注册，才能访问托管对象。\n\n长时间运行的原生调用也可能影响运行时调度。FFI 可以提供机制来释放运行时锁、标识可能阻塞的调用，或协调垃圾回收。在这一边界上作出错误假设，可能引发竞态条件或死锁。\n\n错误与异常\n\n不同语言表示失败的方式不同。C API 可能使用状态码、空指针或线程局部错误状态，而另一种语言则使用异常。\n\n绑定通常会显式转换这些表示形式。异常跨越语言边界传播需要专门支持，一般不能假定这样做是安全的。不支持跨语言栈展开的接口，通常会在异常离开某个运行时之前将其捕获，并转换为文档规定的错误表示形式。"
    },
    {
      "heading": "实现方式",
      "text": "FFI 实现通常采用以下一种或多种方式：\n\n- 编译器支持的声明。 在源代码中声明外部函数及其调用约定，从而支持编译时检查和原生调用生成。\n- 运行时调用接口。 运行时库根据参数类型和返回类型的描述构造调用。libffi 库提供的就是这类底层机制；它本身并不提供完整的语言绑定。\n- 自动生成的绑定。 工具读取声明或接口描述，并生成封装代码。自动生成可以减少重复工作，但无法自动解决所有权或语义上的歧义。\n- 手写适配器。 通过定制的封装来转换复杂对象、维护不变量，并提供适合调用语言的接口。\n\n绑定通常比底层 FFI 机制涵盖的范围更广。它可以包括常量、对象封装、资源管理规则，以及特定语言的便捷功能。如果一个绑定只是照搬外部库的约定，那么即使技术上正确，其接口也可能仍然难以使用。"
    },
    {
      "heading": "示例",
      "text": "Python编程语言提供 ctypes，可以根据声明的原生类型调用共享库中的函数。CPython 还提供了用于构建扩展模块的 C API。这些方式的区别之一，在于适配代码有多少用 Python 编写、多少用 C 编写。\n\nJava 的 Java 原生接口（JNI）支持原生代码与 Java 虚拟机之间的交互。Rust 支持外部函数声明和兼容 C 的接口；外部调用通常需要显式的 unsafe 边界，而绑定可以在其外围构建限制更严格的安全接口。\n\n下面这个简单的 C API 说明了为什么仅有类型信息还不够：\n\nstruct image;\n\nstruct image *image_open(const char *path);\nint image_width(const struct image *img);\nvoid image_close(struct image *img);\n\n绑定需要明确的不只是函数签名。它还需要知道路径的编码方式、如何表示失败、image_open 是否保留路径、各项操作是否线程安全，以及每个成功打开的图像是否都必须且只能调用一次 image_close。\n\n不透明的 struct image 指针使库能够隐藏其内部表示。更高层的封装可以将该指针与自动清理机制关联起来，同时阻止在图像关闭后继续操作。"
    },
    {
      "heading": "用途、性能与局限",
      "text": "FFI 支持复用现有库、在语言之间逐步迁移、集成平台 API，以及访问专门的原生代码。科学软件经常将高层的流程组织与编译后的数值计算例程相结合。机器学习系统也同样通过语言绑定来使用原生计算库和针对特定硬件的实现。\n\n外部调用的开销不一定很大，但具体成本取决于实现和工作负载。兼容的原生组件之间进行直接调用，额外开销可能很小。运行时切换、参数检查、内存分配、字符串转换和数据复制，则可能让其他调用的成本显著增加。因此，大量细粒度调用的成本，可能高于完成同等工作的单次批量操作。\n\nFFI 也会受到目标接口本身的限制。可变参数函数、复杂的原生对象模型、异步回调和平台特有的数据布局，都可能增加绑定的实现或维护难度。库更新可能保留源代码兼容性却破坏二进制兼容性，也可能保留函数签名，却改变绑定所依赖的假设。"
    },
    {
      "heading": "安全与隔离",
      "text": "FFI 通常会削弱调用语言的类型系统和内存管理模型所提供的保证。即使某种语言对数组进行边界检查，也不一定能阻止原生代码越界写入缓冲区。错误的声明或不安全的原生实现，可能给原本内存安全的应用程序引入缓冲区溢出或其他安全漏洞。\n\n安全封装可以通过检查长度、限制指针访问、将所有权规则编码到接口中，以及转换错误，来缩小这一不安全边界。但其安全保证仍取决于底层外部实现及其文档所述契约的正确性。\n\nFFI 本身并不是沙箱（计算机安全）。在同一进程中运行的原生代码，通常可以访问该进程的内存并使用其权限。如果需要隔离，可以使用独立进程，并通过受约束的通信接口与之交互，以建立另一种安全边界；代价是通信开销，以及必须更明确地安排数据交换。"
    }
  ],
  "links": [
    "programming-language",
    "interoperability",
    "c-programming-language",
    "application-programming-interface",
    "process-computing",
    "interprocess-communication",
    "compiler",
    "interpreter",
    "call-stack",
    "operating-system",
    "unicode",
    "garbage-collection",
    "thread-computing",
    "race-condition",
    "deadlock",
    "python-programming-language",
    "virtual-machine",
    "machine-learning",
    "type-system",
    "security-vulnerability",
    "sandbox-computer-security"
  ],
  "sources": [],
  "license": "https://creativecommons.org/licenses/by/4.0/"
}