专栏：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::string&output){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<