763 lines
22 KiB
Markdown
763 lines
22 KiB
Markdown
# 公共组件API参考
|
||
|
||
## 目录
|
||
|
||
- [公共组件API参考](#公共组件api参考)
|
||
- [目录](#目录)
|
||
- [概述](#概述)
|
||
- [错误处理系统](#错误处理系统)
|
||
- [错误码](#错误码)
|
||
- [异常层次结构](#异常层次结构)
|
||
- [错误处理器](#错误处理器)
|
||
- [工具函数](#工具函数)
|
||
- [宏定义](#宏定义)
|
||
- [日志系统](#日志系统)
|
||
- [日志级别](#日志级别)
|
||
- [日志接口](#日志接口)
|
||
- [模块日志](#模块日志)
|
||
- [日志配置](#日志配置)
|
||
- [使用示例](#使用示例)
|
||
- [错误处理示例](#错误处理示例)
|
||
- [日志记录示例](#日志记录示例)
|
||
- [集成示例](#集成示例)
|
||
- [最佳实践](#最佳实践)
|
||
- [错误处理最佳实践](#错误处理最佳实践)
|
||
- [日志记录最佳实践](#日志记录最佳实践)
|
||
- [跨平台考虑](#跨平台考虑)
|
||
|
||
## 概述
|
||
|
||
公共组件模块提供了错误处理和日志记录等基础功能，为整个音频后端系统提供统一的异常处理和日志记录机制。这些组件设计为高性能、线程安全且跨平台，使开发者能够轻松地进行错误处理和系统状态监控。
|
||
|
||
核心特性：
|
||
|
||
- **统一的错误处理**：提供清晰的错误码、异常层次结构和错误处理工具
|
||
- **灵活的日志系统**：支持多级别、多目标（控制台/文件）的日志记录
|
||
- **模块化设计**：允许按模块进行日志和错误处理
|
||
- **高性能**：所有组件设计时考虑了性能开销，适用于实时音频处理
|
||
- **线程安全**：支持多线程环境下的并发操作
|
||
|
||
## 错误处理系统
|
||
|
||
错误处理系统提供了一套完整的错误处理机制，包括错误码、异常类和错误处理工具。
|
||
|
||
### 错误码
|
||
|
||
`ErrorCode`枚举定义了系统中所有可能的错误状态：
|
||
|
||
```cpp
|
||
enum class ErrorCode {
|
||
// 通用错误 (0-999)
|
||
SUCCESS = 0,
|
||
UNKNOWN_ERROR = 1,
|
||
INVALID_ARGUMENT = 2,
|
||
INVALID_OPERATION = 3,
|
||
NOT_IMPLEMENTED = 4,
|
||
OUT_OF_MEMORY = 5,
|
||
OPERATION_TIMED_OUT = 6,
|
||
NOT_INITIALIZED = 7,
|
||
ALREADY_INITIALIZED = 8,
|
||
|
||
// 文件和I/O错误 (1000-1999)
|
||
FILE_NOT_FOUND = 1000,
|
||
FILE_ACCESS_DENIED = 1001,
|
||
FILE_READ_ERROR = 1002,
|
||
FILE_WRITE_ERROR = 1003,
|
||
FILE_FORMAT_ERROR = 1004,
|
||
|
||
// 音频处理错误 (2000-2999)
|
||
AUDIO_FORMAT_ERROR = 2000,
|
||
AUDIO_DEVICE_ERROR = 2001,
|
||
AUDIO_BUFFER_UNDERRUN = 2002,
|
||
AUDIO_BUFFER_OVERRUN = 2003,
|
||
AUDIO_SAMPLE_RATE_MISMATCH = 2004,
|
||
AUDIO_CHANNEL_COUNT_MISMATCH = 2005,
|
||
|
||
// 插件错误 (3000-3999)
|
||
PLUGIN_LOAD_ERROR = 3000,
|
||
PLUGIN_NOT_FOUND = 3001,
|
||
PLUGIN_VERSION_MISMATCH = 3002,
|
||
PLUGIN_INITIALIZATION_ERROR = 3003,
|
||
PLUGIN_COMMUNICATION_ERROR = 3004,
|
||
PLUGIN_EXECUTION_ERROR = 3005,
|
||
PLUGIN_TIMEOUT = 3006,
|
||
|
||
// 通信错误 (4000-4999)
|
||
COMMUNICATION_ERROR = 4000,
|
||
CONNECTION_ERROR = 4001,
|
||
DISCONNECTED = 4002,
|
||
MESSAGE_FORMAT_ERROR = 4003,
|
||
PROTOCOL_ERROR = 4004,
|
||
TIMEOUT = 4005,
|
||
|
||
// 系统错误 (5000-5999)
|
||
SYSTEM_ERROR = 5000,
|
||
PERMISSION_DENIED = 5001,
|
||
NOT_ENOUGH_RESOURCES = 5002
|
||
};
|
||
```
|
||
|
||
错误码按功能域分组，便于管理和扩展。系统还提供了错误分类枚举：
|
||
|
||
```cpp
|
||
enum class ErrorCategory {
|
||
GENERAL,
|
||
FILE,
|
||
AUDIO,
|
||
PLUGIN,
|
||
COMMUNICATION,
|
||
SYSTEM
|
||
};
|
||
```
|
||
|
||
获取错误描述和分类的辅助函数：
|
||
|
||
```cpp
|
||
// 获取错误分类
|
||
ErrorCategory get_error_category(ErrorCode code);
|
||
|
||
// 获取错误码对应的描述信息
|
||
std::string get_error_description(ErrorCode code);
|
||
```
|
||
|
||
### 异常层次结构
|
||
|
||
系统定义了一个异常层次结构，以`AudioBackendException`为基类：
|
||
|
||
```cpp
|
||
// 基础异常类
|
||
class AudioBackendException : public std::exception {
|
||
public:
|
||
explicit AudioBackendException(ErrorCode code,
|
||
const std::string& message = "",
|
||
const std::string& details = "");
|
||
|
||
// 获取错误码
|
||
ErrorCode code() const noexcept;
|
||
|
||
// 获取错误消息
|
||
const std::string& message() const noexcept;
|
||
|
||
// 获取详细信息
|
||
const std::string& details() const noexcept;
|
||
|
||
// 获取完整错误消息
|
||
const char* what() const noexcept override;
|
||
|
||
// 获取错误分类
|
||
ErrorCategory category() const noexcept;
|
||
|
||
// 获取std::error_code
|
||
std::error_code error_code() const noexcept;
|
||
|
||
// 是否是某个错误码
|
||
bool is(ErrorCode code) const noexcept;
|
||
|
||
// 是否属于某个错误分类
|
||
bool is_category(ErrorCategory category) const noexcept;
|
||
};
|
||
```
|
||
|
||
基于基础异常类，系统还定义了特定领域的异常类：
|
||
|
||
```cpp
|
||
// 文件异常
|
||
class FileException : public AudioBackendException;
|
||
|
||
// 音频异常
|
||
class AudioException : public AudioBackendException;
|
||
|
||
// 插件异常
|
||
class PluginException : public AudioBackendException;
|
||
|
||
// 通信异常
|
||
class CommunicationException : public AudioBackendException;
|
||
|
||
// 系统异常
|
||
class SystemException : public AudioBackendException;
|
||
```
|
||
|
||
### 错误处理器
|
||
|
||
`ErrorHandler`类提供了集中式的错误处理机制：
|
||
|
||
```cpp
|
||
class ErrorHandler {
|
||
public:
|
||
// 错误处理回调函数类型
|
||
using ErrorCallback = std::function<void(const AudioBackendException&)>;
|
||
|
||
// 获取单例实例
|
||
static ErrorHandler& instance();
|
||
|
||
// 添加全局错误处理回调
|
||
void add_error_handler(const ErrorCallback& handler);
|
||
|
||
// 移除错误处理回调
|
||
void remove_error_handler(const ErrorCallback& handler);
|
||
|
||
// 处理错误
|
||
void handle_error(const AudioBackendException& exception);
|
||
|
||
// 处理错误（从错误码创建异常）
|
||
void handle_error(ErrorCode code,
|
||
const std::string& message = "",
|
||
const std::string& details = "");
|
||
|
||
// 处理异常捕获
|
||
void handle_exception(std::exception_ptr eptr);
|
||
|
||
// 清除所有错误处理回调
|
||
void clear_handlers();
|
||
};
|
||
```
|
||
|
||
系统还提供了RAII风格的错误处理辅助类：
|
||
|
||
```cpp
|
||
class ScopedErrorHandler {
|
||
public:
|
||
explicit ScopedErrorHandler(ErrorHandler::ErrorCallback handler);
|
||
~ScopedErrorHandler();
|
||
};
|
||
```
|
||
|
||
### 工具函数
|
||
|
||
错误处理系统提供了一系列工具函数：
|
||
|
||
```cpp
|
||
// 根据错误码创建适当的异常
|
||
std::exception_ptr create_exception(ErrorCode code,
|
||
const std::string& message = "",
|
||
const std::string& details = "");
|
||
|
||
// 根据错误码抛出异常
|
||
[[noreturn]] void throw_exception(ErrorCode code,
|
||
const std::string& message = "",
|
||
const std::string& details = "");
|
||
|
||
// 错误检查函数（条件为true时抛出异常）
|
||
void check_error(bool condition,
|
||
ErrorCode error_code,
|
||
const std::string& message = "",
|
||
const std::string& details = "");
|
||
|
||
// 将系统错误码转换为AudioBackend错误码
|
||
ErrorCode system_error_to_error_code(int system_error);
|
||
|
||
// 将std::error_code转换为AudioBackend错误码
|
||
ErrorCode std_error_to_error_code(const std::error_code& ec);
|
||
```
|
||
|
||
### 宏定义
|
||
|
||
系统提供了便捷的错误处理宏：
|
||
|
||
```cpp
|
||
// 检查条件并抛出异常
|
||
#define AUDIO_CHECK_ERROR(condition, error_code, message)
|
||
|
||
// 直接抛出异常
|
||
#define AUDIO_THROW_ERROR(error_code, message)
|
||
|
||
// 处理错误（调用ErrorHandler）
|
||
#define AUDIO_HANDLE_ERROR(error_code, message)
|
||
|
||
// try-catch简化宏
|
||
#define AUDIO_TRY_CATCH_ALL()
|
||
#define AUDIO_CATCH_ALL()
|
||
```
|
||
|
||
## 日志系统
|
||
|
||
日志系统基于spdlog库实现，提供了灵活、高性能的日志记录功能。
|
||
|
||
### 日志级别
|
||
|
||
日志系统定义了以下日志级别：
|
||
|
||
```cpp
|
||
enum class LogLevel {
|
||
TRACE, // 最详细的调试信息
|
||
DEBUG, // 详细的调试信息
|
||
INFO, // 一般信息
|
||
WARN, // 警告信息
|
||
ERR, // 错误信息
|
||
CRITICAL, // 严重错误
|
||
OFF // 关闭日志
|
||
};
|
||
```
|
||
|
||
### 日志接口
|
||
|
||
`Logger`类提供了日志系统的核心功能：
|
||
|
||
```cpp
|
||
class Logger {
|
||
public:
|
||
// 获取单例实例
|
||
static Logger& instance();
|
||
|
||
// 初始化日志系统
|
||
void initialize(const std::string& app_name = "AudioBackend",
|
||
LogLevel console_level = LogLevel::INFO,
|
||
bool file_logging = true,
|
||
const std::string& log_dir = "logs",
|
||
size_t max_file_size = 5 * 1024 * 1024,
|
||
size_t max_files = 3);
|
||
|
||
// 关闭日志系统
|
||
void shutdown();
|
||
|
||
// 设置全局日志级别
|
||
void set_level(LogLevel level);
|
||
|
||
// 设置控制台日志级别
|
||
void set_console_level(LogLevel level);
|
||
|
||
// 设置文件日志级别
|
||
void set_file_level(LogLevel level);
|
||
|
||
// 获取当前日志级别
|
||
LogLevel get_level() const;
|
||
|
||
// 获取日志器
|
||
std::shared_ptr<spdlog::logger> get_logger() const;
|
||
|
||
// 获取特定模块的日志器
|
||
std::shared_ptr<spdlog::logger> get_module_logger(const std::string& module_name);
|
||
|
||
// 刷新日志缓冲区
|
||
void flush();
|
||
|
||
// 便捷的日志记录方法
|
||
template<typename... Args>
|
||
void trace(std::string_view fmt, const Args&... args);
|
||
|
||
template<typename... Args>
|
||
void debug(std::string_view fmt, const Args&... args);
|
||
|
||
template<typename... Args>
|
||
void info(std::string_view fmt, const Args&... args);
|
||
|
||
template<typename... Args>
|
||
void warn(std::string_view fmt, const Args&... args);
|
||
|
||
template<typename... Args>
|
||
void err(std::string_view fmt, const Args&... args);
|
||
|
||
template<typename... Args>
|
||
void critical(std::string_view fmt, const Args&... args);
|
||
};
|
||
```
|
||
|
||
系统还提供了全局日志函数，无需直接访问Logger实例：
|
||
|
||
```cpp
|
||
template<typename... Args>
|
||
inline void log_trace(std::string_view fmt, const Args&... args);
|
||
|
||
template<typename... Args>
|
||
inline void log_debug(std::string_view fmt, const Args&... args);
|
||
|
||
template<typename... Args>
|
||
inline void log_info(std::string_view fmt, const Args&... args);
|
||
|
||
template<typename... Args>
|
||
inline void log_warn(std::string_view fmt, const Args&... args);
|
||
|
||
template<typename... Args>
|
||
inline void log_err(std::string_view fmt, const Args&... args);
|
||
|
||
template<typename... Args>
|
||
inline void log_critical(std::string_view fmt, const Args&... args);
|
||
```
|
||
|
||
### 模块日志
|
||
|
||
系统支持按模块进行日志记录，提供了便捷的模块日志宏：
|
||
|
||
```cpp
|
||
// 创建模块日志器
|
||
#define AUDIO_MODULE_LOGGER(module_name)
|
||
|
||
// 模块级别日志记录宏
|
||
#define AUDIO_LOG_TRACE(...)
|
||
#define AUDIO_LOG_DEBUG(...)
|
||
#define AUDIO_LOG_INFO(...)
|
||
#define AUDIO_LOG_WARN(...)
|
||
#define AUDIO_LOG_ERR(...)
|
||
#define AUDIO_LOG_CRITICAL(...)
|
||
```
|
||
|
||
### 日志配置
|
||
|
||
日志系统支持以下配置选项：
|
||
|
||
- **应用名称**：日志中显示的应用名称
|
||
- **控制台日志级别**：显示在控制台的最低日志级别
|
||
- **文件日志**：是否启用文件日志
|
||
- **日志目录**：日志文件的存储目录
|
||
- **最大文件大小**：单个日志文件的最大大小
|
||
- **最大文件数**：轮转日志的最大文件数量
|
||
|
||
## 使用示例
|
||
|
||
### 错误处理示例
|
||
|
||
**基本错误检查和处理：**
|
||
|
||
```cpp
|
||
#include "common/error.h"
|
||
#include <iostream>
|
||
|
||
using namespace audio_backend::common;
|
||
|
||
void example_error_handling() {
|
||
// 使用错误检查宏
|
||
try {
|
||
bool condition = false; // 假设这是一个失败条件
|
||
AUDIO_CHECK_ERROR(condition, ErrorCode::INVALID_OPERATION,
|
||
"操作无法执行，参数无效");
|
||
} catch (const AudioBackendException& e) {
|
||
std::cout << "捕获异常: " << e.what() << std::endl;
|
||
std::cout << "错误码: " << static_cast<int>(e.code()) << std::endl;
|
||
std::cout << "错误类别: " << static_cast<int>(e.category()) << std::endl;
|
||
}
|
||
|
||
// 直接抛出异常
|
||
try {
|
||
AUDIO_THROW_ERROR(ErrorCode::FILE_NOT_FOUND, "找不到配置文件");
|
||
} catch (const FileException& e) {
|
||
std::cout << "捕获文件异常: " << e.what() << std::endl;
|
||
} catch (const AudioBackendException& e) {
|
||
std::cout << "这不会被执行，因为FileException已经捕获" << std::endl;
|
||
}
|
||
|
||
// 使用错误处理器
|
||
ErrorHandler::instance().add_error_handler([](const AudioBackendException& e) {
|
||
std::cout << "错误处理器: " << e.what() << std::endl;
|
||
});
|
||
|
||
// 当触发错误时，会调用错误处理器
|
||
AUDIO_HANDLE_ERROR(ErrorCode::AUDIO_DEVICE_ERROR, "音频设备初始化失败");
|
||
}
|
||
```
|
||
|
||
**使用作用域错误处理器：**
|
||
|
||
```cpp
|
||
void example_scoped_error_handler() {
|
||
// 创建一个局部作用域的错误处理器
|
||
{
|
||
ScopedErrorHandler handler([](const AudioBackendException& e) {
|
||
std::cout << "作用域错误处理器: " << e.what() << std::endl;
|
||
});
|
||
|
||
// 在这个作用域内，所有错误都会被处理器捕获
|
||
AUDIO_HANDLE_ERROR(ErrorCode::COMMUNICATION_ERROR, "连接超时");
|
||
|
||
} // 离开作用域，错误处理器自动移除
|
||
|
||
// 此处的错误不会被上面的处理器捕获
|
||
AUDIO_HANDLE_ERROR(ErrorCode::PLUGIN_LOAD_ERROR, "插件加载失败");
|
||
}
|
||
```
|
||
|
||
**全局错误处理：**
|
||
|
||
```cpp
|
||
// 全局错误处理函数
|
||
void global_error_handler(const AudioBackendException& e) {
|
||
std::cerr << "全局错误处理: " << e.what() << std::endl;
|
||
|
||
// 可以根据错误类别执行不同操作
|
||
switch (e.category()) {
|
||
case ErrorCategory::FILE:
|
||
// 处理文件错误...
|
||
break;
|
||
case ErrorCategory::AUDIO:
|
||
// 处理音频错误...
|
||
break;
|
||
// 其他错误类别...
|
||
}
|
||
}
|
||
|
||
int main() {
|
||
// 设置全局错误处理器
|
||
ErrorHandler::instance().add_error_handler(global_error_handler);
|
||
|
||
// 现在所有通过ErrorHandler处理的错误都会被全局处理器捕获
|
||
|
||
try {
|
||
// 应用代码...
|
||
} catch (...) {
|
||
// 捕获所有未处理的异常
|
||
ErrorHandler::instance().handle_exception(std::current_exception());
|
||
}
|
||
|
||
return 0;
|
||
}
|
||
```
|
||
|
||
### 日志记录示例
|
||
|
||
**基本日志记录：**
|
||
|
||
```cpp
|
||
#include "common/logger.h"
|
||
|
||
using namespace audio_backend::common;
|
||
|
||
void example_logging() {
|
||
// 初始化日志系统
|
||
Logger::instance().initialize("MyAudioApp", LogLevel::DEBUG);
|
||
|
||
// 使用全局日志函数
|
||
log_info("应用启动");
|
||
log_debug("调试信息: {}", "测试消息");
|
||
|
||
// 带参数的日志
|
||
int param1 = 42;
|
||
std::string param2 = "测试";
|
||
log_info("参数值: {} 和 {}", param1, param2);
|
||
|
||
// 错误日志
|
||
log_err("发生错误: {}", "找不到文件");
|
||
|
||
// 直接使用Logger实例
|
||
Logger::instance().critical("严重错误: 系统无法继续运行");
|
||
|
||
// 刷新日志缓冲区（确保写入磁盘）
|
||
Logger::instance().flush();
|
||
}
|
||
```
|
||
|
||
**模块日志：**
|
||
|
||
```cpp
|
||
#include "common/logger.h"
|
||
|
||
using namespace audio_backend::common;
|
||
|
||
// 定义模块日志器
|
||
AUDIO_MODULE_LOGGER("AudioEngine");
|
||
|
||
class AudioEngine {
|
||
public:
|
||
void initialize() {
|
||
AUDIO_LOG_INFO("音频引擎初始化中...");
|
||
|
||
// 一些初始化代码...
|
||
|
||
if (true /* 初始化成功 */) {
|
||
AUDIO_LOG_INFO("音频引擎初始化成功");
|
||
} else {
|
||
AUDIO_LOG_ERR("音频引擎初始化失败");
|
||
}
|
||
}
|
||
|
||
void process() {
|
||
AUDIO_LOG_TRACE("处理音频数据...");
|
||
|
||
// 一些处理代码...
|
||
|
||
if (false /* 假设发生了问题 */) {
|
||
AUDIO_LOG_WARN("处理过程中发生警告");
|
||
}
|
||
|
||
AUDIO_LOG_DEBUG("完成音频处理，输出样本数: {}", 1024);
|
||
}
|
||
};
|
||
```
|
||
|
||
**日志配置：**
|
||
|
||
```cpp
|
||
void configure_logging() {
|
||
// 完整配置
|
||
Logger::instance().initialize(
|
||
"MyAudioApp", // 应用名称
|
||
LogLevel::INFO, // 控制台日志级别
|
||
true, // 启用文件日志
|
||
"logs", // 日志目录
|
||
5 * 1024 * 1024, // 最大文件大小（5MB）
|
||
3 // 最大文件数
|
||
);
|
||
|
||
// 动态调整日志级别
|
||
Logger::instance().set_level(LogLevel::DEBUG); // 全局级别
|
||
Logger::instance().set_console_level(LogLevel::INFO); // 控制台级别
|
||
Logger::instance().set_file_level(LogLevel::TRACE); // 文件级别
|
||
|
||
// 为特定模块创建日志器
|
||
auto engine_logger = Logger::instance().get_module_logger("Engine");
|
||
auto plugin_logger = Logger::instance().get_module_logger("Plugin");
|
||
|
||
// 使用模块日志器
|
||
engine_logger->info("引擎模块信息");
|
||
plugin_logger->debug("插件模块调试信息");
|
||
}
|
||
```
|
||
|
||
### 集成示例
|
||
|
||
以下示例展示了如何将错误处理和日志系统集成在一起：
|
||
|
||
```cpp
|
||
#include "common/error.h"
|
||
#include "common/logger.h"
|
||
#include <iostream>
|
||
#include <stdexcept>
|
||
|
||
using namespace audio_backend::common;
|
||
|
||
// 自定义错误处理器，将错误记录到日志
|
||
void log_error_handler(const AudioBackendException& e) {
|
||
// 根据错误严重性选择合适的日志级别
|
||
switch (e.category()) {
|
||
case ErrorCategory::SYSTEM:
|
||
case ErrorCategory::PLUGIN:
|
||
log_critical("严重错误: {}", e.what());
|
||
break;
|
||
|
||
case ErrorCategory::AUDIO:
|
||
case ErrorCategory::COMMUNICATION:
|
||
log_err("错误: {}", e.what());
|
||
break;
|
||
|
||
case ErrorCategory::FILE:
|
||
case ErrorCategory::GENERAL:
|
||
default:
|
||
log_warn("警告: {}", e.what());
|
||
break;
|
||
}
|
||
}
|
||
|
||
// 示例函数，模拟可能出错的操作
|
||
void perform_risky_operation() {
|
||
// 假设条件检查失败
|
||
bool success = false;
|
||
|
||
if (!success) {
|
||
// 记录错误并抛出异常
|
||
log_debug("操作失败，即将抛出异常");
|
||
AUDIO_THROW_ERROR(ErrorCode::OPERATION_TIMED_OUT, "操作超时");
|
||
}
|
||
}
|
||
|
||
// 完整集成示例
|
||
int main() {
|
||
try {
|
||
// 初始化日志系统
|
||
Logger::instance().initialize("AudioApp", LogLevel::DEBUG);
|
||
log_info("应用程序启动");
|
||
|
||
// 设置将错误记录到日志的处理器
|
||
ErrorHandler::instance().add_error_handler(log_error_handler);
|
||
log_debug("已注册错误处理器");
|
||
|
||
try {
|
||
// 尝试执行风险操作
|
||
log_info("开始执行操作...");
|
||
perform_risky_operation();
|
||
} catch (const AudioBackendException& e) {
|
||
// 本地处理异常，但不退出
|
||
log_debug("捕获到异常: {}", e.what());
|
||
|
||
// 也可以重新抛出
|
||
throw;
|
||
}
|
||
|
||
log_info("应用程序正常退出");
|
||
} catch (const std::exception& e) {
|
||
// 捕获所有未处理的异常
|
||
log_critical("未处理的异常: {}", e.what());
|
||
return 1;
|
||
}
|
||
|
||
return 0;
|
||
}
|
||
```
|
||
|
||
## 最佳实践
|
||
|
||
### 错误处理最佳实践
|
||
|
||
1. **选择适当的错误处理方式**：
|
||
- 使用错误码返回值处理预期的错误
|
||
- 使用异常处理非预期的错误和严重故障
|
||
- 在性能关键路径上避免使用异常
|
||
|
||
2. **合理分类错误**：
|
||
- 按照错误的性质和严重程度分类
|
||
- 为不同类型的错误提供明确的上下文信息
|
||
|
||
3. **提供详细的错误信息**：
|
||
- 描述发生了什么（错误内容）
|
||
- 解释为什么会发生（错误原因）
|
||
- 建议如何解决（修复方法）
|
||
|
||
4. **集中处理错误**：
|
||
- 使用全局错误处理器统一处理错误
|
||
- 将错误处理与业务逻辑分离
|
||
|
||
5. **实时系统的错误处理**：
|
||
- 避免在音频回调线程中抛出异常
|
||
- 使用错误标志和延迟处理
|
||
- 预先分配错误处理资源，避免动态内存分配
|
||
|
||
### 日志记录最佳实践
|
||
|
||
1. **选择适当的日志级别**：
|
||
- TRACE: 最详细的调试信息，通常仅在开发时启用
|
||
- DEBUG: 详细的调试信息，有助于问题诊断
|
||
- INFO: 正常操作信息，记录系统状态和重要事件
|
||
- WARN: 警告信息，表明可能的问题，但不会导致系统失败
|
||
- ERR: 错误信息，表明功能无法正常工作
|
||
- CRITICAL: 严重错误，系统无法继续运行
|
||
|
||
2. **结构化日志信息**：
|
||
- 使用一致的格式记录日志
|
||
- 包含时间戳、日志级别、模块名称、线程ID等元数据
|
||
- 使用参数化日志而不是字符串拼接
|
||
|
||
3. **避免过多日志**：
|
||
- 避免在高频率循环中记录日志
|
||
- 使用采样或节流技术减少重复日志
|
||
- 注意日志对性能的影响
|
||
|
||
4. **按模块记录日志**：
|
||
- 每个模块使用专门的日志器
|
||
- 模块名称应反映代码结构
|
||
|
||
5. **实时系统的日志记录**：
|
||
- 使用异步日志记录，避免阻塞音频线程
|
||
- 考虑使用环形缓冲区进行临时日志存储
|
||
- 定期刷新日志，而不是每条日志都刷新
|
||
|
||
## 跨平台考虑
|
||
|
||
公共组件模块设计为跨平台工作，但在不同平台上仍有一些注意事项：
|
||
|
||
1. **文件路径处理**：
|
||
- Windows使用反斜杠（`\`）作为路径分隔符
|
||
- Unix/Linux/macOS使用正斜杠（`/`）作为路径分隔符
|
||
- 使用平台无关的路径处理函数
|
||
|
||
2. **文件权限和访问**：
|
||
- 不同平台的文件权限模型存在差异
|
||
- 日志文件创建可能受系统权限限制
|
||
|
||
3. **系统错误转换**：
|
||
- 不同平台的系统错误码不同
|
||
- 使用`system_error_to_error_code()`函数进行统一转换
|
||
|
||
4. **线程安全性**：
|
||
- 所有公共组件都设计为线程安全
|
||
- 不同平台的线程模型存在差异，但API保持一致
|
||
|
||
5. **性能考虑**：
|
||
- 不同平台上日志和错误处理的性能特性可能有所不同
|
||
- 高性能应用应当在各目标平台上进行性能测试 |