专栏：HarmonyOS 三方库适配实战（22/30）核心问题：整数范围、布尔值、字符串编码和空值怎样安全地跨过 ArkTS/C++ 边界？摘要Node-API 桥接函数最重要的工作不是“把值拿出来”，而是拒绝错误的参数数量、类型和范围，并保证失败只走一条可预测路径。本文实现normalizeAscii(input, lowercase)：先读取两个参数，验证字符串和布尔值，再调用纯 C++ 核心并创建返回字符串。代码已为双 ABI 编译并被 ArkTS 类型声明消费；运行时返回值尚未在设备验证。接入位置与最小行为契约沿用 Native 工程的entry/src/main/cpp/napi_init.cpp；需要napi/native_api.h、string、vector与text_core.h。.d.ts放在types/libtextnative/index.d.ts，模块注册表把normalizeAscii映射到NormalizeAscii。下文是桥接切片，不是缺少注册和构建配置也能独立运行的项目。归一化在本例中只承诺：去掉首尾 ASCII 空白、把连续空白合为一个空格、按 lowercase 选择是否转小写。输入' A\tB '的预期是'a b'或'A B'。不要把“归一化”误解为 Unicode NFC/NFKC 或本地化大小写。先写公开契约exportconstnormalizeAscii:(input:string,lowercase:boolean)=string契约已经限定两个事实：输入只接受字符串和布尔值，返回字符串。C++ 层不能悄悄接受数字并自动转字符串，否则.d.ts与运行时行为不一致。图 1：ArkTS 声明、Node-API 校验与 C++ 核心形成三段契约。读取字符串时先问长度boolReadUtf8(napi_env env,napi_value value,std::stringoutput){napi_valuetype type=napi_undefined;if(napi_typeof(env,value,type)!=napi_ok||type!=napi_string){napi_throw_type_error(env,nullptr,"input must be a string");returnfalse;}std::size_t length=0;if(napi_get_value_string_utf8(env,value,nullptr,0,length)!=napi_ok){napi_throw_error(env,nullptr,"failed to read input length");returnfalse