SequoiaDB开发规范：代码风格与最佳实践
项目地址: https://gitcode.com/SequoiaDB/SequoiaDB 概述
SequoiaDB作为一款企业级分布式文档型数据库，其代码库规模庞大且复杂。为了确保代码质量、可维护性和团队协作效率，项目制定了一套严格的开发规范和代码风格指南。本文将从代码组织、命名规范、注释要求、错误处理、内存管理等多个维度，深入解析SequoiaDB的开发规范体系。
代码组织结构
目录结构规范
SequoiaDB采用模块化的目录结构设计，主要目录组织如下：
文件命名规范
| 文件类型 | 命名规范 | 示例 |
|---|---|---|
| 头文件 | .h 后缀，全小写，下划线分隔 | ossTypes.h |
| C++源文件 | .cpp 后缀，全小写，下划线分隔 | utilCommon.cpp |
| C源文件 | .c 后缀，全小写，下划线分隔 | json2rawbson.c |
| JavaScript文件 | .js 后缀，驼峰命名 | common.js |
| 配置文件 | .conf 后缀，全小写 | sdbcm.conf |
编码风格规范
头文件规范
每个头文件必须包含标准的版权声明和文件描述：
/*******************************************************************************
Copyright (C) 2011-Present SequoiaDB Ltd.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Source File Name = ossTypes.h
Descriptive Name = 操作系统抽象类型定义
When/how to use: 跨平台类型定义
Dependencies: N/A
Restrictions: N/A
Change Activity:
defect Date Who Description
====== =========== === ==============================================
11/28/2012 YW Initial Draft
Last Changed =
*******************************************************************************/
#ifndef OSSTYPES_H_
#define OSSTYPES_H_
// 内容...
#endif /* OSSTYPES_H_ */
命名规范
类型定义
// 基本类型使用全大写，下划线分隔
typedef unsigned char UINT8;
typedef unsigned short UINT16;
typedef unsigned int UINT32;
typedef unsigned long long UINT64;
// 结构体使用小写，下划线分隔
struct _utilShellRCItem
{
UINT32 _src ;
INT32 _rc ;
UINT32 _end ;
} ;
typedef _utilShellRCItem utilShellRCItem ;
函数命名
// 动词+名词形式，使用驼峰命名法
SDB_ROLE utilGetRoleEnum( const CHAR *role );
const CHAR* utilDBRoleStr( SDB_ROLE dbrole );
INT32 utilStrToFTMask( const CHAR *pStr, UINT32 &ftMask );
宏定义
// 全大写，下划线分隔
#define OSS_MIN(a, b) (((a) < (b)) ? (a) : (b))
#define OSS_MAX(a, b) (((a) > (b)) ? (a) : (b))
#define SDB_PAGE_SIZE 4096
变量命名
// 成员变量以下划线开头
class commonResult
{
public:
INT32 errno; // 错误码
string detail; // 详细信息
string _internalId; // 内部标识（私有成员）
};
代码格式规范
缩进与空格
- 使用4个空格进行缩进，禁止使用Tab键
- 操作符前后添加空格
- 逗号后添加空格
- 花括号使用K&R风格
// 正确的格式
for ( UINT32 i = 0 ; i < parsed.size() ; ++i )
{
if ( 0 == ossStrcasecmp( SDB_DB_MODE_READONLY_STR,
parsed[ i ].c_str() ) )
{
modeFlag |= SDB_DB_MODE_READONLY ;
}
}
指针和引用
// 指针符号*靠近类型
CHAR* pBuffer;
const CHAR* pStr;
// 引用符号&靠近类型
INT32 utilStrToFTMask( const CHAR *pStr, UINT32 &ftMask );
注释规范
函数注释
/**
* @brief 将字符串转换为容错掩码
* @param pStr 输入字符串，支持"ALL"、"NONE"或具体标志组合
* @param ftMask 输出的容错掩码
* @return 错误码，SDB_OK表示成功
* @note 支持的标志：NOSPC, DEADSYNC, SLOWNODE, TRANSERR
*/
INT32 utilStrToFTMask( const CHAR *pStr, UINT32 &ftMask );
代码块注释
// 使用doxygen格式的注释
/// @brief 数据库角色枚举转换
/// @param role 角色字符串
/// @return 对应的SDB_ROLE枚举值
SDB_ROLE utilGetRoleEnum( const CHAR *role )
{
if ( NULL == role )
return SDB_ROLE_MAX;
else if ( *role == 0 ||
0 == ossStrcasecmp( role, SDB_ROLE_STANDALONE_STR ) )
return SDB_ROLE_STANDALONE ;
// ... 其他判断
}
错误处理规范
错误码定义
SequoiaDB使用统一的错误码体系：
enum SDB_SHELL_RETURN_CODE
{
SDB_SRC_SUC = 0, // 成功
SDB_SRC_EMPTY = 1, // 空结果
SDB_SRC_WARNING = 2, // 警告
SDB_SRC_ERROR = 4, // 错误
SDB_SRC_SYS = 8, // 系统错误
SDB_SRC_INVALIDARG = 127, // 无效参数
// 用户自定义错误码从128开始
SDB_SRC_IO = 128, // IO异常
SDB_SRC_PERM = 129, // 权限错误
SDB_SRC_OOM = 130, // 内存不足
// ... 其他错误码
};
错误处理模式
// 标准的错误处理模式
INT32 functionName( parameters )
{
INT32 rc = SDB_OK;
// 参数检查
if ( NULL == pParam )
{
rc = SDB_INVALIDARG;
goto error;
}
// 业务逻辑
rc = someOperation();
if ( rc != SDB_OK )
{
PD_LOG( PDERROR, "Operation failed: %d", rc );
goto error;
}
done:
return rc;
error:
goto done;
}
日志记录规范
// 使用PD_LOG宏进行日志记录
PD_LOG( PDDEBUG, "Debug information: %s", someValue ); // 调试信息
PD_LOG( PDINFO, "Information: %d", someNumber ); // 一般信息
PD_LOG( PDWARNING, "Warning: %s", warningMessage ); // 警告信息
PD_LOG( PDERROR, "Error occurred: %d", errorCode ); // 错误信息
内存管理规范
资源获取即初始化（RAII）
// 使用智能指针管理资源
#include "ossMem.hpp"
void exampleFunction()
{
// 使用OSS原生内存管理
CHAR* pBuffer = (CHAR*)SDB_OSS_MALLOC( bufferSize );
if ( NULL == pBuffer )
{
rc = SDB_OOM;
goto error;
}
// 使用作用域保护确保资源释放
OSS_SCOPE_EXIT( SDB_OSS_FREE( pBuffer ) );
// 使用资源
// ...
done:
return;
error:
goto done;
}
内存分配检查
// 所有内存分配必须检查返回值
CHAR* pBuffer = (CHAR*)SDB_OSS_MALLOC( size );
if ( NULL == pBuffer )
{
rc = SDB_OOM;
PD_LOG( PDERROR, "Failed to allocate %d bytes", size );
goto error;
}
多线程与并发规范
线程安全设计
// 使用互斥锁保护共享资源
#include "ossLatch.hpp"
class ThreadSafeClass
{
private:
ossSpinXLatch _lock; // 自旋锁，用于高频访问
ossMutex _mutex; // 互斥锁，用于低频访问
public:
void threadSafeMethod()
{
// 使用锁保护临界区
_mutex.get();
OSS_SCOPE_EXIT( _mutex.release() );
// 临界区操作
// ...
}
};
原子操作
// 使用原子操作避免竞态条件
#define OSS_ONCE_INT32_PTR( x ) ( (volatile INT32 *)( &( x ) ) )
#define OSS_ONCE_INT32_REF( x ) ( *( OSS_ONCE_INT32_PTR( x ) ) )
#define OSS_ONCE_INT32_SET( x, v ) ( { OSS_ONCE_INT32_REF( x ) = ( v ) ; } )
#define OSS_ONCE_INT32_GET( x ) ( OSS_ONCE_INT32_REF( x ) )
跨平台开发规范
平台相关代码处理
// 使用预编译指令处理平台差异
#if defined (_WINDOWS)
#define OSS_NEWLINE "\r\n"
#define OSS_NEWLINE_SIZE ( 2 )
#else
#define OSS_NEWLINE "\n"
#define OSS_NEWLINE_SIZE ( 1 )
#define SDB_INVALID_FH (-1)
#endif
// 类型定义跨平台适配
#if defined ( _LINUX ) || defined ( _AIX )
typedef int ossSystemError ;
#elif defined ( _WINDOWS )
typedef DWORD ossSystemError ;
#endif
字节序处理
// 使用统一的字节序转换宏
#define ossEndianConvert4(in,out) \
do { \
const CHAR *pin = (const CHAR *)&in ; \
CHAR *pout = (CHAR*)&out ; \
pout[0] = pin[3] ; \
pout[1] = pin[2] ; \
pout[2] = pin[1] ; \
pout[3] = pin[0] ; \
} while ( FALSE )
性能优化规范
内联函数使用
// 高频调用的简单函数使用内联
OSS_FORCE_INLINE pmdEDUCB *getEDUCB ()
{
return _tlsEDUCB ;
}
// 模板函数自动内联
template<typename T>
OSS_INLINE T ossMin( T a, T b )
{
return ( a < b ) ? a : b ;
}
内存对齐
// 确保关键数据结构的内存对齐
#define ossIsAlignedNative(x) (0==(((ossValuePtr)(x))&(sizeof(void*)-1)))
#define ossIsAligned4(x) (0==(((ossValuePtr)(x))&(4-1)))
#define ossIsAligned8(x) (0==(((ossValuePtr)(x))&(8-1)))
// 结构体对齐指示
struct alignas(64) CacheLineAlignedStruct
{
// 成员变量
};
测试与质量保证
单元测试规范
// 使用GTest框架进行单元测试
#include "gtest/gtest.h"
TEST( UtilTest, RoleEnumConversion )
{
EXPECT_EQ( SDB_ROLE_STANDALONE, utilGetRoleEnum( "standalone" ) );
EXPECT_EQ( SDB_ROLE_DATA, utilGetRoleEnum( "data" ) );
EXPECT_EQ( SDB_ROLE_MAX, utilGetRoleEnum( NULL ) );
EXPECT_EQ( SDB_ROLE_MAX, utilGetRoleEnum( "invalid" ) );
}
静态代码分析
项目使用以下工具进行代码质量检查：
| 工具类型 | 工具名称 | 检查内容 |
|---|---|---|
| 代码风格 | clang-format | 代码格式一致性 |
| 静态分析 | cppcheck | 潜在代码缺陷 |
| 内存检查 | valgrind | 内存泄漏检测 |
| 并发检查 | helgrind | 线程安全问题 |
构建与部署规范
SCons构建配置
# SConstruct文件中的构建配置示例
env.Append(
CPPPATH=[join(engine_dir,'include'),join(engine_dir,'client'),
join(ssl_dir,'include'),join(lz4_dir,'include')],
CPPDEFINES=["__STDC_LIMIT_MACROS", "HAVE_CONFIG_H"]
)
# 平台特定的编译选项
if guess_os == "linux":
env.Append( CXXFLAGS=" -std=c++98 " )
依赖管理
# 依赖项配置示例
boostLibs = [ "thread", "filesystem", "program_options", "system", "chrono" ]
env.Append(
EXTRALIBPATH=[boost_lib_dir, ssl_lib_dir, zlib_lib_dir,
lz4_lib_dir, snappy_lib_dir, intel_decimal_lib_dir]
)
总结
SequoiaDB的开发规范体系体现了企业级软件工程的最佳实践，主要特点包括：
- 严格的代码组织：模块化设计，清晰的目录结构
- 统一的命名规范：类型、函数、变量命名的一致性
- 完善的错误处理：统一的错误码体系和错误处理模式
- 可靠的内存管理：RAII模式，资源自动释放
- 线程安全设计：完善的锁机制和原子操作
- 跨平台支持：统一的平台抽象层
- 性能优化：内联函数、内存对齐等优化手段
- 质量保证：完整的测试体系和静态分析
遵循这些规范不仅能够提高代码质量，还能显著提升团队协作效率和软件的可维护性。对于新加入SequoiaDB开发的工程师，深入理解和严格遵守这些规范是快速融入项目团队的关键。
注意：本文档基于SequoiaDB现有代码库分析得出，实际开发时应以项目最新的官方文档为准。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
