每日一句正能量

在最不期待的时候，反而一切都会变得顺利。
期待往往伴随紧张和控制欲，反而制造阻力；当你真正放下、不执著结果时，能量是松弛的、开放的，事情反而容易自然匹配。顺利不是求来的，是不求之后到来的。

导读

在指导学生参加鸿蒙应用开发大赛时，我发现一个规律——凡是涉及图像处理、实时计算、音视频编解码的项目，最终都绕不开 NAPI（Native API）。ArkTS 声明式 UI 开发效率极高，但在 CPU 密集型任务面前，纯 ArkTS 的性能往往捉襟见肘。HarmonyOS 6.x 的 NAPI 已经实现了 ArkTS 与 C/C++ 的桥接，但开发门槛高、内存管理复杂、线程安全问题频发。HarmonyOS 7.0 极有可能在 NAPI 层引入更简洁的绑定语法和更安全的内存模型。本文将以"图片滤镜处理引擎"为实战案例，完整演示从 CMake 配置、C++ 实现、NAPI 绑定到 ArkTS 调用的全流程，并给出性能对比与线程安全最佳实践。

一、HarmonyOS 6.x NAPI 现状：能桥接，但写起来费劲

6.1 中，开发者通过 NAPI 将 C/C++ 库封装为 ArkTS 可调用的模块，核心机制是：

课堂场景中的典型崩溃：

• C++ 返回的 ArrayBuffer 被 ArkTS 垃圾回收后，C++ 侧仍访问该内存，导致 use-after-free；
• 异步任务在 Worker 线程中直接调用 napi_create_string，触发 SIGSEGV（NAPI 函数必须在主线程调用）；
• napi_wrap 的 finalize 回调未注册，C++ 对象内存永不释放，应用运行 10 分钟后 OOM。

二、HarmonyOS 7.0 NAPI 演进推演

2.1 Unified IR 与跨语言内联

7.0 的方舟编译器 Next 可能引入 Unified IR（参见本系列第六篇），这意味着 ArkTS 与 C++ 的边界不再像 6.x 那样"厚重"：

• 编译器可以看到 ArkTS 调用 C++ 函数时的类型信息，自动生成更高效的参数序列化代码；
• 小型 C++ 函数（如简单的数学运算）可能被编译器跨语言内联，消除 NAPI 桥接开销；
• 统一的对象头格式，使 ArkTS 对象和 C++ 对象在堆上布局兼容，减少 napi_wrap 的包裹层数。

2.2 简化绑定语法

7.0 可能引入声明式 NAPI 绑定，类似 Node-API 的 node-addon-api 或 Dart FFI：

// 7.0 推演：声明式 NAPI 绑定
// native/ImageProcessor.d.ts
declare module 'native/ImageProcessor' {
  // 编译器自动生成 NAPI 胶水代码
  @native.Binding('libimageproc.so')
  export function applyFilter(
    imageData: ArrayBuffer,
    width: number,
    height: number,
    filterType: FilterType
  ): ArrayBuffer;

  @native.Binding('libimageproc.so')
  export async function applyFilterAsync(
    imageData: ArrayBuffer,
    width: number,
    height: number,
    filterType: FilterType
  ): Promise<ArrayBuffer>;
}

2.3 托管内存模型

7.0 可能提供托管的跨堆引用：

• C++ 持有的 ArkTS 对象引用由系统自动追踪生命周期；
• 当 ArkTS 对象被 GC 时，C++ 侧的引用自动失效（返回 null 而非野指针）；
• 减少手动 napi_ref / napi_delete_reference 的繁琐操作。

三、实战：图片滤镜处理引擎

以下基于 6.x/7.0 的 NAPI 规范，实现一个完整的图片滤镜模块。

3.1 工程结构

entry/src/main/
├── cpp/
│   ├── CMakeLists.txt
│   ├── image_filter.cpp      # C++ 核心算法
│   ├── napi_binding.cpp      # NAPI 绑定层
│   └── types/
│       └── image_filter.d.ts # 类型声明
└── ets/
    └── pages/
        └── FilterDemo.ets    # ArkTS 调用端

3.2 CMake 配置

# cpp/CMakeLists.txt
cmake_minimum_required(VERSION 3.10)
project(imagefilter)

# NDK 工具链（由 DevEco 自动注入）
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# 编译优化
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -O3 -ffast-math -fPIC")
set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -O3 -fPIC")

# 源码
add_library(imagefilter SHARED
    image_filter.cpp
    napi_binding.cpp
)

# 链接 NAPI 库
target_link_libraries(imagefilter
    ace_napi.z
    hilog_ndk.z
)

# 7.0 推演：自动导出符号，无需手动维护 exports.map
set_target_properties(imagefilter PROPERTIES
    CXX_VISIBILITY_PRESET default
)

图1：NAPI 跨语言调用链路图

图片内容说明（中文）：纵向分层流程图。最上层"ArkTS 应用"：调用 ImageProcessor.applyFilter()。中间层"NAPI 运行时"：包含"参数序列化（ArkTS类型→C类型）“、“线程安全检查”、“异常转换”。最下层"C++ 原生层”：执行 image_filter.cpp 中的算法。返回时用虚线箭头表示"C++结果→ArkTS对象"。各层之间用双向箭头连接，右侧标注"主线程调用"和"异步线程调用"两条路径。

3.3 C++ 核心算法

// cpp/image_filter.cpp
#include <cstdint>
#include <algorithm>
#include <cmath>

namespace imageproc {

// 灰度滤镜：Y = 0.299R + 0.587G + 0.114B
void GrayscaleFilter(uint8_t* data, int width, int height) {
    const int pixelCount = width * height;
    for (int i = 0; i < pixelCount; ++i) {
        int offset = i * 4;  // RGBA
        uint8_t gray = static_cast<uint8_t>(
            0.299 * data[offset] +
            0.587 * data[offset + 1] +
            0.114 * data[offset + 2]
        );
        data[offset] = gray;
        data[offset + 1] = gray;
        data[offset + 2] = gray;
        // Alpha 保持不变
    }
}

// 高斯模糊（简化 3x3 核）
void BlurFilter(uint8_t* data, int width, int height) {
    const int kernel[3][3] = {
        {1, 2, 1},
        {2, 4, 2},
        {1, 2, 1}
    };
    const int kernelSum = 16;

    // 创建临时缓冲区
    uint8_t* temp = new uint8_t[width * height * 4];
    std::copy(data, data + width * height * 4, temp);

    for (int y = 1; y < height - 1; ++y) {
        for (int x = 1; x < width - 1; ++x) {
            int r = 0, g = 0, b = 0;
            for (int ky = -1; ky <= 1; ++ky) {
                for (int kx = -1; kx <= 1; ++kx) {
                    int offset = ((y + ky) * width + (x + kx)) * 4;
                    int weight = kernel[ky + 1][kx + 1];
                    r += temp[offset] * weight;
                    g += temp[offset + 1] * weight;
                    b += temp[offset + 2] * weight;
                }
            }
            int dstOffset = (y * width + x) * 4;
            data[dstOffset] = static_cast<uint8_t>(r / kernelSum);
            data[dstOffset + 1] = static_cast<uint8_t>(g / kernelSum);
            data[dstOffset + 2] = static_cast<uint8_t>(b / kernelSum);
        }
    }
    delete[] temp;
}

}  // namespace imageproc

3.4 NAPI 绑定层

// cpp/napi_binding.cpp
#include "napi/native_api.h"
#include "image_filter.cpp"
#include "hilog/log.h"

static constexpr int32_t ARG_COUNT = 4;

// 同步调用：applyFilter(imageData, width, height, filterType)
napi_value ApplyFilter(napi_env env, napi_callback_info info) {
    size_t argc = ARG_COUNT;
    napi_value args[ARG_COUNT] = {nullptr};
    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);

    // 解析 ArrayBuffer
    uint8_t* imageData = nullptr;
    size_t byteLength = 0;
    napi_get_arraybuffer_info(env, args[0], reinterpret_cast<void**>(&imageData), &byteLength);

    // 解析 width, height, filterType
    int32_t width = 0, height = 0, filterType = 0;
    napi_get_value_int32(env, args[1], &width);
    napi_get_value_int32(env, args[2], &height);
    napi_get_value_int32(env, args[3], &filterType);

    // 执行滤镜（直接修改输入 buffer，避免拷贝）
    switch (filterType) {
        case 0:
            imageproc::GrayscaleFilter(imageData, width, height);
            break;
        case 1:
            imageproc::BlurFilter(imageData, width, height);
            break;
        default:
            napi_throw_error(env, nullptr, "Unknown filter type");
            return nullptr;
    }

    // 返回原 ArrayBuffer（已原地修改）
    return args[0];
}

// 异步调用：避免阻塞主线程
struct AsyncContext {
    napi_async_work work = nullptr;
    napi_deferred deferred = nullptr;
    uint8_t* imageData = nullptr;
    size_t byteLength = 0;
    int32_t width = 0;
    int32_t height = 0;
    int32_t filterType = 0;
    napi_ref arrayBufferRef = nullptr;
};

napi_value ApplyFilterAsync(napi_env env, napi_callback_info info) {
    size_t argc = ARG_COUNT;
    napi_value args[ARG_COUNT] = {nullptr};
    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);

    // 创建 Promise
    napi_value promise;
    napi_deferred deferred;
    napi_create_promise(env, &deferred, &promise);

    // 构建异步上下文
    auto* context = new AsyncContext();
    context->deferred = deferred;
    napi_get_arraybuffer_info(env, args[0], reinterpret_cast<void**>(&context->imageData), &context->byteLength);
    napi_get_value_int32(env, args[1], &context->width);
    napi_get_value_int32(env, args[2], &context->height);
    napi_get_value_int32(env, args[3], &context->filterType);
    napi_create_reference(env, args[0], 1, &context->arrayBufferRef);

    // 创建异步任务
    napi_value resourceName;
    napi_create_string_utf8(env, "ApplyFilterAsync", NAPI_AUTO_LENGTH, &resourceName);

    napi_create_async_work(env, nullptr, resourceName,
        // 执行回调（Worker 线程）
        [](napi_env env, void* data) {
            auto* ctx = static_cast<AsyncContext*>(data);
            switch (ctx->filterType) {
                case 0:
                    imageproc::GrayscaleFilter(ctx->imageData, ctx->width, ctx->height);
                    break;
                case 1:
                    imageproc::BlurFilter(ctx->imageData, ctx->width, ctx->height);
                    break;
            }
        },
        // 完成回调（主线程）
        [](napi_env env, napi_status status, void* data) {
            auto* ctx = static_cast<AsyncContext*>(data);
            napi_value result;
            napi_get_reference_value(env, ctx->arrayBufferRef, &result);

            if (status == napi_ok) {
                napi_resolve_deferred(env, ctx->deferred, result);
            } else {
                napi_value error;
                napi_create_error(env, nullptr, nullptr, &error);
                napi_reject_deferred(env, ctx->deferred, error);
            }

            napi_delete_reference(env, ctx->arrayBufferRef);
            napi_delete_async_work(env, ctx->work);
            delete ctx;
        },
        context, &context->work);

    napi_queue_async_work(env, context->work);
    return promise;
}

// 模块导出
EXTERN_C_START
static napi_value Init(napi_env env, napi_value exports) {
    napi_property_descriptor desc[] = {
        { "applyFilter", nullptr, ApplyFilter, nullptr, nullptr, nullptr, napi_default, nullptr },
        { "applyFilterAsync", nullptr, ApplyFilterAsync, nullptr, nullptr, nullptr, napi_default, nullptr }
    };
    napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
    return exports;
}
EXTERN_C_END

static napi_module demoModule = {
    .nm_version = 1,
    .nm_flags = 0,
    .nm_filename = nullptr,
    .nm_register_func = Init,
    .nm_modname = "imagefilter",
    .nm_priv = nullptr,
    .reserved = { 0 }
};

extern "C" __attribute__((constructor)) void RegisterImageFilterModule() {
    napi_module_register(&demoModule);
}

3.5 ArkTS 调用端

// ets/pages/FilterDemo.ets
import imageFilter from 'libimagefilter.so';

enum FilterType {
  GRAYSCALE = 0,
  BLUR = 1
}

@Entry
@Component
struct FilterDemo {
  @State pixelMap: PixelMap | null = null;
  @State processingTime: number = 0;
  @State isProcessing: boolean = false;

  async applyGrayscale(): Promise<void> {
    if (!this.pixelMap) return;

    this.isProcessing = true;
    const start = Date.now();

    // 获取 PixelMap 的 ArrayBuffer
    const imageInfo = await this.pixelMap.getImageInfo();
    const buffer = new ArrayBuffer(imageInfo.size.width * imageInfo.size.height * 4);

    // 读取像素数据到 buffer
    await this.pixelMap.readPixelsToBuffer(buffer);

    // 调用 NAPI（异步，不阻塞 UI）
    await imageFilter.applyFilterAsync(
      buffer,
      imageInfo.size.width,
      imageInfo.size.height,
      FilterType.GRAYSCALE
    );

    // 写回 PixelMap
    await this.pixelMap.writeBufferToPixels(buffer);

    this.processingTime = Date.now() - start;
    this.isProcessing = false;
  }

  build() {
    Column() {
      if (this.pixelMap) {
        Image(this.pixelMap)
          .width('100%')
          .height(400)
          .objectFit(ImageFit.Contain)
      }

      Text(`处理耗时: ${this.processingTime}ms`)
        .fontSize(16)
        .margin(8)

      Button('灰度滤镜 (NAPI)')
        .enabled(!this.isProcessing)
        .onClick(() => this.applyGrayscale())

      Button('高斯模糊 (NAPI)')
        .enabled(!this.isProcessing)
        .onClick(() => this.applyBlur())
    }
    .padding(16)
  }

  async applyBlur(): Promise<void> {
    // 类似灰度，传入 FilterType.BLUR
  }
}

四、性能对比：ArkTS vs C++ NAPI

图2：ArkTS 纯实现 vs C++ NAPI 性能基准对比图

图片内容说明（中文）：横向分组柱状图，共三组测试场景。每组两根柱子，蓝色"ArkTS纯实现"，绿色"C++ NAPI"。①1280×720图片灰度：ArkTS约450ms，NAPI约28ms。②1280×720图片模糊：ArkTS约1200ms，NAPI约85ms。③1000×1000矩阵乘法：ArkTS约800ms，NAPI约45ms。底部标注"测试设备：Mate 60 Pro，Release模式"。

关键洞察：

• 计算密集型任务（图像处理、矩阵运算、加密算法）用 NAPI 收益巨大，可达 10~20 倍加速；
• IO 密集型或已高度优化的任务（JSON 解析、正则匹配）用 NAPI 收益有限，甚至因桥接开销而变慢；
• 结论：不要盲目将所有逻辑下沉到 C++，只在 CPU 热点处使用 NAPI。

五、内存管理最佳实践

5.1 ArrayBuffer 生命周期管理

6.x 中最常见的内存陷阱是 ArrayBuffer 的跨堆引用：

// ❌ 错误：保存 ArkTS ArrayBuffer 指针供后续使用
uint8_t* g_savedBuffer = nullptr;

napi_value BadExample(napi_env env, napi_callback_info info) {
    napi_get_arraybuffer_info(env, args[0], reinterpret_cast<void**>(&g_savedBuffer), &len);
    // 危险！当 ArkTS GC 回收 ArrayBuffer 后，g_savedBuffer 变成野指针
    return nullptr;
}

// ✅ 正确：使用 napi_ref 保持引用，或立即拷贝数据
napi_value GoodExample(napi_env env, napi_callback_info info) {
    napi_ref ref;
    napi_create_reference(env, args[0], 1, &ref);  // 保持引用，防止 GC

    uint8_t* buffer = nullptr;
    napi_get_arraybuffer_info(env, args[0], reinterpret_cast<void**>(&buffer), &len);

    // 使用完毕后在 finalize 中释放 ref
    // 或立即拷贝数据到 C++ 堆
    uint8_t* copy = new uint8_t[len];
    std::copy(buffer, buffer + len, copy);

    napi_delete_reference(env, ref);  // 立即释放引用
    return nullptr;
}

5.2 C++ 对象绑定与释放

// 封装类管理 C++ 对象生命周期
class ImageProcessor {
public:
    explicit ImageProcessor(int width, int height) : width_(width), height_(height) {}
    ~ImageProcessor() = default;

    void Process(uint8_t* data, int filterType) {
        // ...
    }

private:
    int width_;
    int height_;
};

// NAPI 构造函数
napi_value ImageProcessorConstructor(napi_env env, napi_callback_info info) {
    int width = 0, height = 0;
    // 解析参数...

    auto* processor = new ImageProcessor(width, height);

    napi_value jsObject;
    napi_create_object(env, &jsObject);

    // 绑定 C++ 对象到 JS 对象，并注册析构回调
    napi_wrap(env, jsObject, processor,
        [](napi_env env, void* finalize_data, void* finalize_hint) {
            delete static_cast<ImageProcessor*>(finalize_data);
            OH_LOG_INFO(LOG_APP, "ImageProcessor destroyed");
        },
        nullptr, nullptr);

    return jsObject;
}

5.3 内存泄漏检测

// 在模块初始化时启用内存追踪（调试用）
#ifdef DEBUG
#include <malloc.h>

void CheckMemoryLeak() {
    struct mallinfo info = mallinfo();
    OH_LOG_INFO(LOG_APP, "Allocated memory: %{public}d bytes", info.uordblks);
}
#endif

六、线程安全实践

6.1 NAPI 线程模型规则

6.2 线程安全的数据传递

// 在 Worker 线程和主线程之间安全传递数据
struct ThreadSafeContext {
    std::mutex mutex;
    std::vector<uint8_t> resultData;
    bool isDone = false;
};

// Worker 线程：只操作 C++ 数据
void WorkerThread(ThreadSafeContext* ctx, const std::vector<uint8_t>& input) {
    std::vector<uint8_t> output = HeavyComputation(input);

    std::lock_guard<std::mutex> lock(ctx->mutex);
    ctx->resultData = std::move(output);
    ctx->isDone = true;
}

// 主线程回调：通过 NAPI 返回结果
void CompleteCallback(napi_env env, napi_status status, void* data) {
    auto* ctx = static_cast<ThreadSafeContext*>(data);

    std::lock_guard<std::mutex> lock(ctx->mutex);
    napi_value result;
    napi_create_arraybuffer(env, ctx->resultData.size(), nullptr, &result);
    uint8_t* buffer = nullptr;
    napi_get_arraybuffer_info(env, result, reinterpret_cast<void**>(&buffer), nullptr);
    std::copy(ctx->resultData.begin(), ctx->resultData.end(), buffer);

    napi_resolve_deferred(env, ctx->deferred, result);
    delete ctx;
}

七、7.0 可能的增强与开发者建议

7.1 预期增强

7.2 何时使用 NAPI？

// DecisionTree.ts
export function shouldUseNAPI(task: TaskProfile): boolean {
  if (task.type === 'cpu_intensive' && task.duration > 50) {
    return true;  // CPU 密集型且耗时超过 50ms
  }
  if (task.type === 'memory_intensive' && task.dataSize > 10 * 1024 * 1024) {
    return true;  // 大数据量处理（>10MB）
  }
  if (task.requires === 'existing_cpp_library') {
    return true;  // 需要复用现有 C++ 库
  }
  if (task.type === 'io_bound') {
    return false;  // IO 密集型用 ArkTS 足够
  }
  return false;
}

八、结语

NAPI 是鸿蒙生态的"性能后门"——它让 ArkTS 应用能够触及 C++ 的极致性能，但也带来了内存管理和线程安全的复杂性。HarmonyOS 6.x 的 NAPI 已经完成了"从 0 到 1"的桥接验证，证明 ArkTS 与 C++ 可以协同工作。而 7.0 的简化绑定语法、托管内存模型和 Unified IR 优化，正在将 NAPI 从"专家工具"转变为"常规武器"。

对于高校学生开发者，NAPI 是理解"跨语言边界"的绝佳窗口。当你亲手写下一个 C++ 滤镜算法，通过 NAPI 桥接到 ArkTS，在真机上看到处理速度从 450ms 降到 28ms 时，你就在亲历系统软件开发的魅力。

但请记住：NAPI 是手术刀，不是斧头。只在真正需要性能加速的地方使用它，否则复杂的内存管理和调试成本会吞噬掉所有收益。

转载自：https://blog.csdn.net/u014727709/article/details/162933611
欢迎 👍点赞✍评论⭐收藏，欢迎指正