SDK开发C++接口定义潜规则

摘要: 集成是个需要小心谨慎的工作，不光需要思考已经发生的情况，还要思考更多可能发生的各种状况，为了尽可能避开潜在麻烦，总结了一些生活中解决办法。主要针对C++接口。

前言

在很大很大的生产环境中，我们工作只是生产过程的一个环节，这就导致了我们经常会使用别人提供动态库，组件，插件等等，我们也会提供给别人相同的东西可以让我们的产品接入到他人的产品中。但是东西多了，迭代久了，业务膨胀，越来越多人使用总会出现这样那样的问题，越往后期，大家更多的是关心你提供什么功能，如何使用功能，以及接下来要说的接口。

原则

接口定义需要考虑东西很多，系统性，兼容性，易用性等等。

1. 接口定义需要通俗易懂，符合使用者习惯, 人们更多关心函数名字，参数类型，对文档关心程度并不高，通俗易懂的接口会减少使用者查阅文档时间，也减少我们自己的时间。

2. 接口必须做到兼容性，而且已做好接口不能改动, 别人用了你的接口, 如果改动会导致使用者的代码改动，使用人一定情绪，所以要么内部适配，要么新增接口以满足新的需求，命名上面尽量使用版本相关后缀例如_V1, _V2。少用Ex，各个版本的接口风格要尽量一致。

3. 资源最好能在使用的时候加载，可通过设定初始化反初始化接口,要和业接口配合, 相同的业务功能使用相同的接口。

4. 常用日志，错误码，断言。日志包括Debug/Error/Inf三个等级，错误码不可重复，如果使用他人提供SDK，错误要尽量兼容， 否则使用错误模块类型 + 错误码。断言能保证程序健全性，但需要非常熟悉代码。

注意事项

不要申请过大的栈内存

当接口被过多的封装，层层嵌套，软件运行过程中，栈资源就很紧张，如果申请过大内存，当程序运行就会导致栈溢出。实际栈的大小只有2M，申请栈内存最好不大于10k，堆栈都是内存，不同就是栈内存使用完自动释放，堆内存需要new/malloc，使用完需要手动释放。

谁申请谁释放。

不要内部申请了内存，外部释放，或者外部申请内存内部释放。这样在堆上申请很难定位，并且难以找到真正错误位置。

输入参数拷贝走

外部传入的参数，特别是申请堆内存，内部如果要使用不要直接使用参数，最好能拷贝到内部申请的变量里。

字符指针参数加个长度

字符串参数有传递通过字符指针char *p，可以对外提供指针长度Len，内部很难控制指针，不能判定*p内存到底来自哪里，是否转换，是否正确，所以加入长度以确定实际内存大小。

字节对齐

字节对齐在结构体上问题较多，上面说到申请栈内存不要过大，同样申请一个结构体也可能出现问题，可能结构体本身也很大，尽量拆分结构体。有时使用者使用强制字节对齐，会导致结构体实际占用内存不同。

结构体内部定义使用数组

结构体内部尽量使用数组或结构体数组，不要使用指针或长度，如果是堆内存很难定位，扩展性可以加入byte[Num]数组，长度大小可以通过是否扩展判断，如果扩展很多参数长度可以很大一般（64 - 256）

线程安全

要保证接口线程安全，如果是初始化反初始化本身无法做到线程安全，但初始化后所有接口调用都要保证线程安全, 需要查看是否有全局变量，适当加锁。

使用回调用户自定义数据

回调的时候使用用户自定义数据 void* pUserData，通过强转能获取使用者定义数据结构，通过数据结构调用相关回调函数。