御盾先看结论与判断条件
- 导出符号能被解析只证明名称和装载满足最低条件，不证明调用约定、结构体大小、字段偏移和所有权一致。
- 公开 C ABI 应使用固定宽度整数、显式版本与 struct_size，并把扩展字段追加到末尾，避免重排旧字段。
- 指针、size_t、long、枚举和函数指针会受 ABI 与编译选项影响，不能拿一个架构的 sizeof 代替全部目标。
- 跨 SO 的分配与释放必须由同一所有权契约管理，调用者不能用自己的 allocator 释放另一模块创建的内存。
- CMake 或自定义构建参数要固定 NDK、ABI、API level、宏、packing 与可见性，预编译库仍需独立核验。
- SO/VMP 变换后要重新检查 ABI 静态断言、导出表、动态依赖和真实调用，旧二进制的通过结果不能继承。
链接成功只验证符号，不验证数据布局
两个 SO 通过 extern "C" 共享函数名后，动态链接器能够找到符号，并不代表调用者与实现者对参数有相同理解。调用约定、整数宽度、结构体 padding、字段偏移、函数指针签名和内存所有权任一项不同，都可能让调用在入口处看似正常，却在读取后续字段、释放缓冲区或回调时崩溃。ABI 门禁必须覆盖数据契约，不只检查 nm 或 readelf 能看到名称。
最隐蔽的问题来自同名头文件的漂移。主应用编译时使用 v2 头文件，预编译插件仍按 v1 布局写入；或者两个模块都声称 v1，却因为 packing 宏、编译器选项和条件字段不同得到不同 sizeof。C 结构体不会在运行时携带反射元数据，消费者只按固定偏移读内存，因此错误通常表现为随机值、越界指针或延迟释放崩溃。
发布前应为每个公开结构体登记规范名称、ABI 版本、总大小、对齐、每个字段偏移、字段语义、所有权和最小可接受长度。调用者与实现者分别从自己的编译产物生成报告，再比较规范值。只在源码层肉眼确认字段顺序，无法发现预处理宏、平台类型和编译参数带来的实际布局差异。
| 检查 | 能确认 | 不能确认 | 失败表现 |
|---|---|---|---|
| 导出符号存在 | 名称可被查找 | 参数布局和所有权 | 装载后调用崩溃 |
| DT_NEEDED 完整 | 依赖名称已声明 | 运行时版本与搜索路径 | 设备上缺库 |
| 头文件一致 | 源码声明看似相同 | 双方实际编译布局 | 字段偏移错读 |
| sizeof 相同 | 总占用字节一致 | 每个字段偏移一致 | 中间字段错位 |
| 单 ABI 通过 | 一个目标布局正确 | 其他 ABI 指针与对齐 | 部分设备崩溃 |
| 调用成功一次 | 一个输入路径可执行 | 版本协商与所有权边界 | 升级或释放时崩溃 |
每个 Android ABI 都要独立计算布局
Android ABIs 说明每个 ABI 具有自己的调用约定、寄存器、对齐和设备支持范围。arm64-v8a、armeabi-v7a、x86_64 与 x86 的指针宽度和对齐不完全相同，包含 pointer、size_t 或函数指针的结构体会产生不同 sizeof 与 offsetof。跨 SO 契约可以在不同 ABI 有不同规范值，但同一 ABI 的生产者与消费者必须完全一致。
固定宽度整数能减少歧义。公开字段优先使用 uint32_t、int64_t 等类型，不用 long、bool 或裸 enum 承担稳定线协议，因为这些类型的宽度或表示可能受平台与编译器影响。指针字段不可避免时，要把指向内容、长度、只读性、生命周期和释放函数写进契约。结构体内嵌 size_t 需要接受不同 ABI 大小，或改用固定宽度长度并验证可表示范围。
对齐不是把所有结构体强制 pack(1)。过度 packing 可能产生非自然对齐访问，改变性能和某些架构上的访问要求，也会让第三方编译器设置更难追踪。更稳妥的做法是使用自然布局，显式记录 alignof、sizeof 与 offsetof，并通过静态断言锁定每个 ABI。若协议确实需要 packed 格式，应把它当作序列化字节格式，不直接把未对齐缓冲区转为结构体指针。
| 类型 | 主要风险 | 建议 | 必须记录 |
|---|---|---|---|
| uint32_t 与 int64_t | 语义范围仍可能误用 | 优先用于稳定整数 | 单位、范围和字节序 |
| long | ABI 间宽度可能不同 | 避免公开契约 | 若保留则逐 ABI 断言 |
| bool | 语言和编译器表示差异 | 改用 uint8_t 加枚举值 | 允许值集合 |
| enum | 底层宽度与未知值 | 使用固定宽度整数 | 版本和未知值处理 |
| size_t | 随指针宽度变化 | 仅限同 ABI 内部或改固定宽度 | 最大值与转换 |
| pointer | 宽度、地址空间和所有权 | 配套长度与释放函数 | 生命周期和可空性 |
struct_size 和 abi_version 要参与运行握手
公开结构体应把 abi_version 与 struct_size 放在开头。生产者写入自己理解的版本和总大小，消费者在读取其他字段前先验证这两个值。struct_size 允许旧消费者只读取已知前缀，也允许新消费者判断旧生产者没有追加字段。版本号则表达不兼容语义变化，例如字段单位改变、所有权反转或回调约定调整。两者缺一都会让兼容判断依赖猜测。
可兼容扩展通常只在末尾追加字段，并保持旧字段的类型、顺序和语义不变。消费者访问新字段前检查 struct_size 是否覆盖该字段末端，未覆盖就使用明确默认值。不能在中间插入字段、重排成员或复用保留位改变含义；这些操作会让旧二进制按错误偏移读后续字段。删除字段也应保留占位或提升 ABI 主版本。
握手失败必须在调用入口返回清晰错误，不能继续读取后面的指针。错误分类至少包括 unsupported-version、struct-too-small、struct-too-large-policy、invalid-field-range 和 missing-release-callback。记录实际与期望的大小、版本、ABI、调用者库 build ID 和提供者库 build ID，但不转储 payload 内容。这样线上异常可以定位到契约，而不是等到随机内存访问才暴露。
| 变化 | 兼容策略 | 消费者动作 | 版本处理 |
|---|---|---|---|
| 末尾追加可选字段 | 前缀兼容 | 先查 struct_size | 可保持主版本 |
| 字段单位改变 | 不兼容 | 拒绝旧语义 | 提升主版本 |
| 中间插入字段 | 不兼容 | 禁止读取 | 提升主版本 |
| 字段类型改变 | 不兼容 | 拒绝布局 | 提升主版本 |
| 保留字段启用 | 需预先定义 | 检查能力位和大小 | 按契约决定 |
| 回调所有权改变 | 不兼容 | 拒绝混用释放路径 | 提升主版本 |
内存所有权比 sizeof 更容易被遗漏
结构体布局完全一致，仍可能因分配与释放跨模块而崩溃。一个 SO 使用自己的 allocator 创建缓冲区，另一个 SO 直接 free，若运行库、分配器或构建配置不同，行为没有可靠保证。公开接口应明确 borrowed、caller-owned、callee-owned 或 shared lifetime，并为 callee-owned 数据提供由创建方实现的 release 回调。调用者只调用回调，不猜测分配方式。
指针必须与长度、可空性和有效期成组定义。payload 只在函数调用期间有效，还是直到调用 release 前有效；回调是否允许异步保存；context 由谁持有；失败时 release 是否仍需调用，都要写在头文件注释与测试中。把裸指针放进结构体却没有生命周期契约，静态断言全部通过也无法阻止 use-after-free。
回调函数指针同样属于 ABI。参数类型、返回值、调用次数、调用线程和重入规则必须固定。不要让 C++ lambda 捕获、std::function、虚函数对象或异常越过 C 边界。可用 void* context 携带不透明状态，但创建与销毁仍由同一模块负责。回调内部若失败，应返回固定错误码，不能让 C++ exception 穿过另一 SO 的 C 栈帧。
跨 SO 边界保持 C，C++ 留在模块内部
Android C++ library support 说明 C++ 异常、RTTI 和 libc++ 链接方式受构建系统与运行库选择影响。跨 SO 直接暴露 std::string、std::vector、模板类、虚表或 C++ exception，会把编译器 ABI、运行库版本、allocator 和 type_info 一并带入契约。即使当前链接成功，独立升级任一模块都可能改变隐藏布局和符号依赖。
稳定边界应导出 extern "C" 函数，参数只使用明确定义的 C POD、固定宽度整数、字节缓冲区和函数指针。模块内部可以继续使用 C++ 容器与异常，但必须在导出入口转换为 C 结果和所有权明确的缓冲区。异常不得穿过边界；每个导出函数都应捕获内部异常并返回固定错误枚举，同时保持输出结构未部分初始化。
这不是说 C ABI 自动稳定。packing、宏、编译器扩展、位域、匿名 union 和条件成员仍会改变布局。公开头文件应限制这些特性，通过编译器警告与静态断言验证，并在发布中保留预处理后的契约摘要。若必须使用位标志，采用固定宽度整数和公开 mask，不依赖 C 位域的排列。
| 对象 | 边界建议 | 原因 | 替代方式 |
|---|---|---|---|
| 固定宽度整数 | 允许 | 表示稳定 | 记录范围与单位 |
| C POD 前缀 | 允许并断言 | 可检查布局 | 版本加 struct_size |
| 字节缓冲区 | 允许并配长度 | 不暴露容器布局 | 配套 release |
| std::string 或 vector | 禁止公开 | 布局与 allocator 耦合 | 指针、长度和释放函数 |
| C++ exception | 禁止跨边界 | unwind 与运行库耦合 | 固定错误枚举 |
| 虚函数对象 | 禁止公开 | vtable 与编译器 ABI | 不透明 handle 加 C 函数 |
构建参数必须成为 ABI 证据的一部分
Android NDK CMake 说明 toolchain 配置会固定 ABI、平台版本和第三方库导入方式。生产者与消费者应记录 NDK 版本、CMake toolchain、ANDROID_ABI、ANDROID_PLATFORM、编译器、语言标准、packing 宏和关键预处理定义。接口库最好由单一公共头文件生成，两侧都将头文件摘要写入构建回执，避免复制后静默漂移。
NDK with other build systems 强调非标准构建要显式固定 NDK toolchain、API level、ABI 和目标。使用 Bazel、Make、Rust FFI 或供应商脚本时，也要输出等价参数并证明最终对象属于目标 ABI。构建命令正确只能说明配置意图，第三方预编译库的内部选项仍未知，需要用公开头文件、对象属性和运行握手独立核验。
Android NDK common problems 列出的 API level、缺失符号、STL、异常类型和错误依赖装载，会与结构体问题同时出现。门禁应先确认架构和动态依赖，再判断布局；否则把 x86_64 库误装到 arm64 或加载了旧 SO 时，任何 offsetof 调查都会偏离真实对象。故障清单帮助建立排查顺序，不替代目标设备的实际调用。
用静态断言在每个编译目标锁定契约
下面的 Bash 脚本接收目标 ABI 的 NDK clang 包装器，以及期望的结构体总大小和字段偏移。它在临时目录生成公开示例头文件与 C11 测试单元，通过 _Static_assert 检查 sizeof、alignof 和 offsetof。期望值来自版本化 ABI 规范，而不是脚本运行时自行接受当前布局，因此任一编译参数或头文件变化都会使编译失败。
示例结构体把 abi_version 与 struct_size 放在开头，使用固定宽度 request_id，payload 指针配 payload_size，callee-owned 缓冲区配 release 回调和 context。脚本验证所有数字参数、编译器可执行性和 ABI 标签，不接受任意 shell 片段。它不会链接或运行 SO，也不会读取私有路径、密钥和客户数据，适合作为每个 ABI 构建任务中的静态门禁。
静态断言通过只证明当前编译单元符合登记布局。生产者与消费者都要独立编译同一测试，并比较编译器身份与头文件摘要；随后还要进行运行握手、数据往返和释放测试。若 SO/VMP 改变最终产物，应在变换后重新执行导出表、依赖和设备回归，不能用变换前对象文件的断言代替。
#!/usr/bin/env bash
set -euo pipefail
if [ "$#" -ne 9 ]; then
exit 2
fi
compiler=$1
abi=$2
expected_size=$3
off_version=$4
off_size=$5
off_request=$6
off_payload=$7
off_payload_size=$8
off_release=$9
case "$abi" in
arm64-v8a|armeabi-v7a|x86_64|x86) ;;
*) exit 2 ;;
esac
for value in "$expected_size" "$off_version" "$off_size" "$off_request" "$off_payload" "$off_payload_size" "$off_release"; do
case "$value" in
''|*[!0-9]*) exit 2 ;;
esac
done
if [ ! -x "$compiler" ]; then
exit 2
fi
work_dir=$(mktemp -d)
trap 'find "$work_dir" -type f -delete; rmdir "$work_dir"' EXIT
header=$work_dir/abi_contract.h
test_file=$work_dir/layout_test.c
object_file=$work_dir/layout_test.o
cat > "$header" <<'HEADER'
#ifndef ABI_CONTRACT_H
#define ABI_CONTRACT_H
#include <stddef.h>
#include <stdint.h>
typedef void (*yd_release_fn)(const uint8_t *, size_t, void *);
typedef struct yd_packet_v1 {
uint32_t abi_version;
uint32_t struct_size;
uint64_t request_id;
const uint8_t *payload;
size_t payload_size;
yd_release_fn release;
void *context;
} yd_packet_v1;
#endif
HEADER
cat > "$test_file" <<TEST
#include <stddef.h>
#include "abi_contract.h"
_Static_assert(sizeof(yd_packet_v1) == $expected_size, "size mismatch");
_Static_assert(offsetof(yd_packet_v1, abi_version) == $off_version, "version offset");
_Static_assert(offsetof(yd_packet_v1, struct_size) == $off_size, "size offset");
_Static_assert(offsetof(yd_packet_v1, request_id) == $off_request, "request offset");
_Static_assert(offsetof(yd_packet_v1, payload) == $off_payload, "payload offset");
_Static_assert(offsetof(yd_packet_v1, payload_size) == $off_payload_size, "payload size offset");
_Static_assert(offsetof(yd_packet_v1, release) == $off_release, "release offset");
int abi_contract_compiles(void) { return 0; }
TEST
"$compiler" -std=c11 -Wall -Wextra -Werror -c "$test_file" -o "$object_file"
if [ ! -s "$object_file" ]; then
exit 3
fi
printf '%s\n' "ABI layout contract compiled for $abi"readelf 用来核对 ELF 身份，不直接证明结构体布局
GNU readelf 可以检查 ELF header、program header、dynamic section、符号、重定位和 unwind 信息。对跨 SO 契约，它适合确认机器架构、ELF class、导出函数、DT_NEEDED、SONAME 和 build ID，排除装错架构、缺少依赖或导出入口消失。结构体字段偏移通常不会作为稳定 ABI 元数据出现在发布 ELF 中，因此还需要编译期断言和运行握手。
readelf 输出要与最终 SO 摘要绑定。检查中间未剥离库，只能说明中间对象；打包、strip、签名或 SO/VMP 后的文件可能不同。门禁应对最终 APK 中提取的库再次核对 header、dynamic 和 symbol，再与构建时记录比较。静态字段存在也不证明动态加载、回调或异常传播成功，目标设备测试仍不可省略。
符号可见性应最小化，只导出稳定 C ABI 入口。隐藏内部 C++ 符号可以减少意外交叉依赖，但不能修复已经错误的结构体契约。若升级后发现导出表未变却仍崩溃，应优先比较 struct_size、offsetof、packing 宏、头文件摘要、调用者与提供者 build ID，以及释放回调是否属于正确模块。
设备回归要验证握手、往返与释放
运行测试应让生产者填充所有字段，消费者先验证版本和大小，再复制可读字段并调用 release。用例覆盖最小合法前缀、完整 v1、未知高版本、过小 struct_size、null payload、零长度、最大允许长度、缺失 release、重复 release 和异步持有。每个结果记录错误枚举，不允许以崩溃作为版本拒绝方式。
每个目标 ABI 都要在代表设备上测试调用者与提供者的版本组合，包括旧调用者加新提供者、新调用者加旧提供者、同版本重建和 SO/VMP 后候选。保护前后比较结构体往返、回调线程、所有权与错误码。单一 ABI 或模拟器通过不能代表其他指针宽度、对齐和设备加载器组合。
准备接入评估时，可在御盾中央平台提交最终 APK、各 ABI 的 SO 摘要和 build ID、公共头文件摘要、布局规范、静态断言回执、readelf 报告、所有权说明、版本矩阵和设备结果。登录、注册、申请、价格与控制台动作统一由中央平台承接。没有同候选证据时应保留待验证，不写兼容通过、性能收益或攻击阻断。
事实依据与适用边界
以下内容区分官方事实、本文工程判断和不能外推的范围，避免把设计建议写成未经验证的产品结论。
| 本文判断 | 事实或工程依据 | 适用限制 |
|---|---|---|
| Android 各 ABI 具有独立调用约定、寄存器、对齐和设备支持范围。 | Android ABIs 描述 Android 支持 ABI 的架构、调用与兼容边界。 | 声明支持某 ABI 不证明对应 SO 已被构建、打包并在设备上验证。 |
| C++ 异常、RTTI 和 libc++ 链接方式受构建系统与运行库选择影响。 | Android C++ library support 描述 C++ runtime、异常和 RTTI 配置。 | 编译选项存在不证明跨 SO 的 type_info、unwind、allocator 和对象布局完整兼容。 |
| NDK 兼容故障常涉及 API level、缺失符号、STL、异常类型和依赖装载。 | Android NDK common problems 汇总常见构建与运行故障。 | 故障清单不能替代目标 ABI 的实际加载、结构体握手和所有权回归。 |
| CMake toolchain 配置会固定 ABI、平台版本和第三方库导入方式。 | Android NDK CMake 描述 NDK toolchain 与相关 CMake 参数。 | CMake 配置不能揭示已预编译第三方二进制的全部内部编译选项。 |
| 非标准构建系统需要显式固定 NDK toolchain、API level、ABI 与目标。 | NDK with other build systems 描述在其他构建系统中配置 NDK 编译目标的要求。 | 参数正确不证明第三方库、运行库和目标设备动态加载已经兼容。 |
| readelf 可以查看 ELF header、program header、dynamic section、符号、重定位和 unwind 信息。 | GNU readelf 描述各类 ELF 检查选项与输出。 | 静态 ELF 字段存在不证明结构体字段布局、动态调用和异常传播成功。 |
| 跨 SO C 结构体应使用 abi_version、struct_size 和追加式字段扩展。 | 工程判断：显式前缀让消费者在读取后续字段前判断已知布局和兼容范围。 | 版本与大小握手仍需同 ABI 静态断言、运行调用和所有权测试。 |
| 跨模块内存应由创建方提供 release 回调或在同一 allocator 契约内释放。 | 工程判断：结构体布局一致不能消除不同运行库、分配器和生命周期带来的释放风险。 | 具体 allocator 与线程规则需要依据双方实现和最终构建配置验证。 |
工程常见问题
两个 SO 能成功链接，为什么结构体仍可能崩溃？
链接器主要确认符号和依赖，不能证明双方的 sizeof、offsetof、对齐、packing、字段语义和所有权一致。错误通常在读取指针或释放内存时暴露。
只比较 sizeof 是否足以判断布局兼容？
不足。总大小相同仍可能有不同字段偏移。要同时断言 alignof、每个公开字段的 offsetof、类型宽度、版本和 struct_size。
使用 pragma pack(1) 能否彻底消除 ABI 差异？
不能。它会引入非自然对齐和访问风险，也不能解决指针宽度、类型语义、所有权与调用约定。更适合把 packed 数据当作序列化字节格式解析。
为什么不能跨 SO 直接传 std::string？
std::string 布局、allocator、运行库和编译器 ABI 可能不同。稳定边界应使用字节指针、长度与由创建方实现的 release 函数。
静态断言通过后还需要设备测试吗？
需要。静态断言只覆盖一个编译单元布局，不能证明两个最终 SO 实际互调、版本握手、动态装载、异步生命周期和释放回调正确。
申请跨 SO ABI 契约评估要准备什么？
准备最终 APK、各 ABI 的 SO 摘要与 build ID、公共头文件、布局规范、编译参数、静态断言、readelf 报告、所有权说明和设备版本矩阵，再通过御盾中央平台提交。