完美架构的设计哲学与实践方法论

“完美架构不是设计出来的是演化出来的。核心是高内聚低耦合 开闭原则 依赖倒置。抓住三个关键点边界清晰、变化隔离、可测试。沟通上用架构图 契约测试对齐认知代码组织遵循六边形架构调试建立可观测性体系。”一、完美架构的六大核心原则1.1 架构原则金字塔┌─────────────────────────────────────────────────────────────────────────────┐ │ 架构原则金字塔 │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────┐ │ │ │ 可观测 │ ← 监控、日志、链路追踪 │ │ ─┴─────────────┴─ │ │ ┌─────────────────┐ │ │ │ 可测试 │ ← 单元测试、集成测试、E2E │ │ ─┴─────────────────┴─ │ │ ┌───────────────────────┐ │ │ │ 可扩展 │ ← 插件化、SPI、配置化 │ │ ─┴───────────────────────┴─ │ │ ┌─────────────────────────────┐ │ │ │ 高内聚低耦合 │ ← 单一职责、接口隔离 │ │ ─┴─────────────────────────────┴─ │ │ ┌───────────────────────────────────┐ │ │ │ 开闭原则(OCP) │ ← 对扩展开放,对修改关闭 │ │ ─┴───────────────────────────────────┴─ │ │ ┌─────────────────────────────────────────┐ │ │ │ 依赖倒置(DIP) │ ← 依赖抽象,不依赖具体 │ │ ─┴─────────────────────────────────────────┴─ │ │ ┌───────────────────────────────────────────────┐ │ │ │ 单一职责(SRP) │ ← 一个类只做一件事 │ │ ─┴───────────────────────────────────────────────┴─ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘1.2 架构设计的灵魂三问问题核心考量判断标准这个模块为什么存在单一职责能否用一句话描述清楚这个模块依赖什么依赖倒置依赖的是抽象还是具体这个模块被谁依赖接口隔离依赖方是否需要所有接口二、如何抓住技术点MECE框架2.1 技术点分解方法论/** * brief 技术点分解框架 - MECE原则 * * MECE Mutually Exclusive, Collectively Exhaustive * 相互独立完全穷尽 */ ​ /* * 步骤1: 领域分解 * * 以工业网关为例按MECE原则分解 * * 工业网关 * ├── 数据采集 (Data Acquisition) * │ ├── 有线采集 * │ │ ├── RS485/Modbus * │ │ ├── CAN/CANopen * │ │ └── Ethernet/Profinet * │ └── 无线采集 * │ ├── 4G/5G * │ ├── LoRa * │ └── WiFi/BT * ├── 数据处理 (Data Processing) * │ ├── 协议转换 * │ ├── 数据清洗 * │ ├── 边缘计算 * │ └── 存储管理 * ├── 数据传输 (Data Transmission) * │ ├── MQTT/CoAP * │ ├── HTTP/HTTPS * │ └── TCP/UDP私有协议 * └── 设备管理 (Device Management) * ├── 远程配置 * ├── OTA升级 * ├── 状态监控 * └── 故障诊断 */ ​ /* * 步骤2: 技术选型矩阵 * * | 需求 | 方案A | 方案B | 选型依据 | * |-------------|-------------|-------------|---------------------| * | 进程间通信 | D-Bus | Unix Socket | 复杂度vs性能 | * | 数据存储 | SQLite | TimescaleDB | 嵌入式vs时序 | * | 消息队列 | RabbitMQ | ZeroMQ | 可靠性vs轻量 | * | 序列化 | Protobuf | JSON | 性能vs可读性 | * | 日志系统 | syslog | spdlog | 标准vs特性 | */ ​ /* * 步骤3: 接口边界定义 * * 关键问题 * 1. 哪些功能对外暴露(API) * 2. 哪些功能内部实现(Impl) * 3. 哪些功能可插拔(SPI) */2.2 技术决策记录模板# 技术决策记录 (Architecture Decision Record, ADR) ​ ## ADR-001: 选择SocketCAN作为CAN通信方案 ​ **状态**: 已采纳 ​ **上下文**: 需要支持3路CAN总线通信波特率250k-1M要求实时性1ms。 ​ **决策**: 采用Linux内核原生SocketCAN框架通过PF_CAN套接字通信。 ​ **理由**: 1. 内核原生支持无需额外驱动开发 2. 支持多路CAN并发 3. 与标准Socket API一致学习成本低 4. 支持CAN FD扩展 ​ **后果**: - 正面: 开发效率高稳定可靠 - 负面: 需要Linux 3.2内核旧系统不支持 ​ **替代方案**: - 直接操作/dev/can设备: 工作量大不推荐 - 使用第三方库libcan: 额外依赖三、如何沟通模块开发契约先行3.1 模块间通信契约/** * file contracts/rs485_contract.h * brief RS485模块契约定义 * * design_pattern Contract Pattern - 先定义契约后实现 * * 沟通流程 * 1. 团队共同评审契约 * 2. 使用Mock实现并行开发 * 3. 契约测试保证一致性 */ ​ #ifndef _RS485_CONTRACT_H_ #define _RS485_CONTRACT_H_ ​ /** * struct Rs485Contract * brief RS485模块契约 * * 这是模块间唯一的沟通凭证 * 任何修改必须经过团队评审。 */ typedef struct Rs485Contract { /* 前置条件 (Preconditions) */ /** 波特率必须为: 9600, 19200, 38400, 115200 */ int valid_baudrate; /** 数据位必须为: 5,6,7,8 */ int valid_data_bits; /** 停止位必须为: 1,2 */ int valid_stop_bits; /* 后置条件 (Postconditions) */ /** open()成功后is_open必须为true */ int (*is_open)(void* handle); /** write()返回后数据必须已发送或缓存 */ int (*is_data_sent)(void* handle); /* 不变量 (Invariants) */ /** 任何时候读写操作不能同时进行(RS485半双工) */ int (*is_idle)(void* handle); /** 错误后模块必须能自动恢复 */ int (*can_recover)(void* handle); /* 性能契约 */ /** 读操作延迟 100ms */ int max_read_latency_ms; /** 写操作吞吐 1000 bytes/s */ int min_write_throughput; } Rs485Contract; ​ #endif3.2 契约测试并行开发的关键/** * file test/contract_test.c * brief 契约测试 - 确保实现符合契约 * * 团队B可以在契约定义后立即开始开发 * 因为契约测试保证了接口的正确性。 */ ​ #include rs485_contract.h #include assert.h ​ /** * brief 契约测试函数 * * 这个测试在实现之前就可以编写 */ void test_rs485_contract(Rs485Contract* impl) { void* handle; int ret; /* 测试前置条件 */ /* 无效波特率应该返回错误 */ ret impl-open(/dev/ttyS0, 12345, handle); assert(ret -1); /* 无效波特率应失败 */ /* 有效波特率应该成功 */ ret impl-open(/dev/ttyS0, 115200, handle); assert(ret 0); /* 测试后置条件 */ /* open后is_open必须为true */ assert(impl-is_open(handle) 1); /* 测试不变量 */ /* 读写不能同时进行 */ assert(impl-is_idle(handle) 1); /* 测试性能契约 */ struct timespec start, end; clock_gettime(CLOCK_MONOTONIC, start); uint8_t buffer[1024]; ret impl-read(handle, buffer, 1024, 100); clock_gettime(CLOCK_MONOTONIC, end); long latency (end.tv_sec - start.tv_sec) * 1000 (end.tv_nsec - start.tv_nsec) / 1000000; /* 延迟不能超过契约约定 */ assert(latency impl-max_read_latency_ms); impl-close(handle); }四、如何组合代码六边形架构4.1 六边形架构端口与适配器┌─────────────────────────────────────────────────────────────────────────────┐ │ 六边形架构 (Hexagonal Architecture) │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────┐ │ │ │ 应用核心层 │ │ │ │ (Domain) │ │ │ │ │ │ │ │ • 业务逻辑 │ │ │ │ • 实体 │ │ │ │ • 领域服务 │ │ │ └────────┬────────┘ │ │ │ │ │ ┌────────────────────────┼────────────────────────┐ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ │ │ 左端口 │ │ 端口 │ │ 右端口 │ │ │ │ (驱动者) │ │ (接口) │ │ (被驱动者) │ │ │ └───────┬───────┘ └───────────────┘ └───────┬───────┘ │ │ │ │ │ │ ▼ ▼ │ │ ┌───────────────┐ ┌───────────────┐ │ │ │ 适配器 │ │ 适配器 │ │ │ │ (REST API) │ │ (DB/MQ) │ │ │ └───────────────┘ └───────────────┘ │ │ │ │ │ │ ▼ ▼ │ │ ┌───────────────┐ ┌───────────────┐ │ │ │ Web浏览器 │ │ PostgreSQL │ │ │ └───────────────┘ └───────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘4.2 目录结构示例# # 六边形架构目录结构 # ​ src/ ├── domain/ # 领域层核心业务逻辑 │ ├── entity/ # 实体 │ │ ├── device.h/c # 设备实体 │ │ ├── can_frame.h/c # CAN帧实体 │ │ └── modbus_pdu.h/c # Modbus PDU实体 │ │ │ ├── service/ # 领域服务 │ │ ├── data_aggregator.h/c # 数据聚合服务 │ │ ├── protocol_converter.h/c # 协议转换服务 │ │ └── alarm_service.h/c # 告警服务 │ │ │ └── repository/ # 仓储接口端口 │ ├── device_repository.h # 设备仓储接口 │ └── data_repository.h # 数据仓储接口 │ ├── application/ # 应用层用例 │ ├── usecase/ │ │ ├── collect_data.h/c # 采集数据用例 │ │ ├── send_command.h/c # 发送命令用例 │ │ └── sync_config.h/c # 同步配置用例 │ │ │ └── dto/ # 数据传输对象 │ ├── device_dto.h/c │ └── can_frame_dto.h/c │ ├── infrastructure/ # 基础设施层适配器 │ ├── adapter/ # 适配器实现 │ │ ├── rs485_adapter.h/c # RS485适配器 │ │ ├── can_adapter.h/c # CAN适配器 │ │ ├── mqtt_adapter.h/c # MQTT适配器 │ │ └── sqlite_adapter.h/c # SQLite适配器 │ │ │ ├── config/ # 配置 │ │ └── app_config.h/c │ │ │ └── logger/ # 日志 │ └── logger.h/c │ ├── interface/ # 接口层端口实现 │ ├── web/ # HTTP接口 │ │ ├── http_server.h/c │ │ └── api_handler.h/c │ │ │ ├── cli/ # 命令行接口 │ │ └── cli_handler.h/c │ │ │ └── message/ # 消息接口 │ └── message_handler.h/c │ └── shared/ # 共享模块 ├── error.h/c # 错误定义 ├── types.h # 类型定义 └── utils.h/c # 工具函数五、如何组合设计模式模式语言5.1 模式组合示例CAN数据处理/** * file domain/service/can_data_processor.c * brief CAN数据处理服务 - 设计模式组合示例 * * 这个模块展示了如何组合使用多个设计模式 * - Strategy Pattern: 不同CAN协议策略 * - Observer Pattern: 数据变化通知 * - Chain of Responsibility: 数据处理链 * - Factory Pattern: 策略创建 * - Template Method: 处理流程模板 */ ​ #include can_data_processor.h ​ /* 1. Strategy Pattern - 协议策略 */ /** * brief CAN协议策略接口 */ typedef struct CanProtocolStrategy { /** 协议名称 */ const char* name; /** 解析CAN帧 */ int (*parse)(const HalCanFrame* frame, void* output, size_t* out_len); /** 编码为CAN帧 */ int (*encode)(const void* data, HalCanFrame* frame); /** 验证帧有效性 */ int (*validate)(const HalCanFrame* frame); } CanProtocolStrategy; ​ /* 具体策略实现 */ static int canopen_parse(const HalCanFrame* frame, void* output, size_t* out_len); static int modbus_can_parse(const HalCanFrame* frame, void* output, size_t* out_len); static int j1939_parse(const HalCanFrame* frame, void* output, size_t* out_len); ​ /* 2. Chain of Responsibility - 处理链 */ /** * brief 数据处理链节点 */ typedef struct ProcessingNode { /** 节点名称 */ const char* name; /** 处理函数 */ int (*process)(const HalCanFrame* input, HalCanFrame* output); /** 下一个节点 */ struct ProcessingNode* next; } ProcessingNode; ​ /* 构建处理链: 过滤 → 去重 → 转换 → 缓存 */ static ProcessingNode* build_processing_chain(void) { ProcessingNode* head NULL; ProcessingNode* curr NULL; /* 节点1: 过滤无效帧 */ head create_filter_node(); curr head; /* 节点2: 去重 */ curr-next create_deduplicate_node(); curr curr-next; /* 节点3: 协议转换 */ curr-next create_convert_node(); curr curr-next; /* 节点4: 缓存 */ curr-next create_cache_node(); return head; } ​ /* 3. Observer Pattern - 观察者 */ /** * brief 观察者列表 */ typedef struct ObserverList { void (*callback)(const HalCanFrame* frame, void* user_data); void* user_data; struct ObserverList* next; } ObserverList; ​ static ObserverList* g_observers NULL; ​ /** * brief 注册观察者 */ void can_data_register_observer(void (*callback)(const HalCanFrame*, void*), void* user_data) { ObserverList* obs (ObserverList*)malloc(sizeof(ObserverList)); obs-callback callback; obs-user_data user_data; obs-next g_observers; g_observers obs; } ​ /** * brief 通知所有观察者 */ static void notify_observers(const HalCanFrame* frame) { ObserverList* curr g_observers; while (curr) { curr-callback(frame, curr-user_data); curr curr-next; } } ​ /* 4. Template Method - 处理模板 */ /** * brief CAN数据处理模板 * * 定义处理骨架子类实现具体步骤 */ typedef struct CanDataProcessor { /* 模板方法 - 不可覆盖 */ int (*process)(struct CanDataProcessor* self, const HalCanFrame* input); /* 钩子方法 - 可覆盖 */ int (*pre_process)(struct CanDataProcessor* self, const HalCanFrame* input); int (*do_process)(struct CanDataProcessor* self, const HalCanFrame* input); int (*post_process)(struct CanDataProcessor* self, const HalCanFrame* input); /* 策略 */ CanProtocolStrategy* strategy; /* 处理链 */ ProcessingNode* chain; } CanDataProcessor; ​ /** * brief 模板方法实现 */ static int processor_template(CanDataProcessor* self, const HalCanFrame* input) { HalCanFrame working_frame *input; int ret; /* 步骤1: 预处理 */ if (self-pre_process) { ret self-pre_process(self, working_frame); if (ret ! 0) return ret; } /* 步骤2: 核心处理 - 走处理链 */ if (self-chain) { ProcessingNode* node self-chain; while (node) { ret node-process(working_frame, working_frame); if (ret ! 0) return ret; node node-next; } } /* 步骤3: 后处理 */ if (self-post_process) { ret self-post_process(self, working_frame); if (ret ! 0) return ret; } /* 通知观察者 */ notify_observers(working_frame); return 0; } ​ /* 5. Factory Pattern - 创建处理器 */ /** * brief 处理器工厂 */ typedef struct ProcessorFactory { CanDataProcessor* (*create)(const char* type); } ProcessorFactory; ​ CanDataProcessor* create_can_processor(const char* type) { CanDataProcessor* processor (CanDataProcessor*)calloc(1, sizeof(CanDataProcessor)); processor-process processor_template; processor-chain build_processing_chain(); /* 根据类型选择策略 */ if (strcmp(type, CANopen) 0) { processor-strategy canopen_strategy; } else if (strcmp(type, ModbusCAN) 0) { processor-strategy modbus_can_strategy; } else if (strcmp(type, J1939) 0) { processor-strategy j1939_strategy; } return processor; }5.2 模式组合的原则┌─────────────────────────────────────────────────────────────────────────────┐ │ 设计模式组合原则 │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ 1. 【单一职责】每个模式解决一个具体问题 │ │ - Strategy: 解决算法变化 │ │ - Observer: 解决状态通知 │ │ - Factory: 解决对象创建 │ │ │ │ 2. 【开闭原则】组合而非继承 │ │ - 通过Strategy替换算法无需修改上下文 │ │ - 通过Observer添加监听器无需修改被观察者 │ │ │ │ 3. 【最少知识】只和直接朋友通信 │ │ - Chain of Responsibility: 每个节点只知下一个 │ │ - Mediator: 通过中介者协调不直接交互 │ │ │ │ 4. 【依赖倒置】依赖抽象不依赖具体 │ │ - Factory返回接口指针 │ │ - Strategy定义为函数指针表 │ │ │ └─────────────────────────────────────────────────────────────────────────────┘六、如何架构调试可观测性体系6.1 可观测性三支柱/** * file shared/observability.h * brief 可观测性框架 * * 三支柱: Metrics(指标) Logging(日志) Tracing(链路追踪) */ ​ #ifndef _OBSERVABILITY_H_ #define _OBSERVABILITY_H_ ​ #include stdint.h ​ /* 1. Metrics - 指标采集 */ ​ /** * brief 指标类型 */ typedef enum { METRIC_COUNTER, /** 计数器: 请求总数, 错误总数 */ METRIC_GAUGE, /** 仪表盘: 当前连接数, 内存使用 */ METRIC_HISTOGRAM /** 直方图: 延迟分布, 包大小分布 */ } MetricType; ​ /** * brief 指标定义宏 */ #define DEFINE_COUNTER(name) \ static volatile uint64_t g_counter_##name 0; \ static inline void counter_##name##_inc(void) { \ __atomic_add_fetch(g_counter_##name, 1, __ATOMIC_RELAXED); \ } \ static inline uint64_t counter_##name##_get(void) { \ return __atomic_load_n(g_counter_##name, __ATOMIC_RELAXED); \ } ​ /* 使用示例 */ DEFINE_COUNTER(can_rx_total) /* CAN总接收帧数 */ DEFINE_COUNTER(can_tx_total) /* CAN总发送帧数 */ DEFINE_COUNTER(can_errors) /* CAN错误计数 */ DEFINE_COUNTER(udp_packets) /* UDP包数 */ ​ /* 2. Logging - 结构化日志 */ ​ /** * brief 日志级别 */ typedef enum { LOG_LEVEL_ERROR 0, /** 错误: 需要人工介入 */ LOG_LEVEL_WARN 1, /** 警告: 需要关注 */ LOG_LEVEL_INFO 2, /** 信息: 正常流程 */ LOG_LEVEL_DEBUG 3, /** 调试: 开发阶段 */ LOG_LEVEL_TRACE 4 /** 追踪: 详细调试 */ } LogLevel; ​ /** * brief 结构化日志宏 * * 使用printf格式自动添加时间戳、文件、行号、函数名 */ #define LOG_ERROR(fmt, ...) \ log_write(LOG_LEVEL_ERROR, __FILE__, __LINE__, __FUNCTION__, fmt, ##__VA_ARGS__) ​ #define LOG_WARN(fmt, ...) \ log_write(LOG_LEVEL_WARN, __FILE__, __LINE__, __FUNCTION__, fmt, ##__VA_ARGS__) ​ #define LOG_INFO(fmt, ...) \ log_write(LOG_LEVEL_INFO, __FILE__, __LINE__, __FUNCTION__, fmt, ##__VA_ARGS__) ​ #define LOG_DEBUG(fmt, ...) \ log_write(LOG_LEVEL_DEBUG, __FILE__, __LINE__, __FUNCTION__, fmt, ##__VA_ARGS__) ​ /* 3. Tracing - 链路追踪 */ ​ /** * brief 追踪上下文 */ typedef struct TraceContext { uint64_t trace_id; /** 全局追踪ID */ uint64_t span_id; /** 当前Span ID */ uint64_t parent_span_id;/** 父Span ID */ struct timespec start; /** 开始时间 */ const char* name; /** 操作名称 */ } TraceContext; ​ /** * brief 开始追踪 */ TraceContext* trace_start(const char* name) { TraceContext* ctx (TraceContext*)malloc(sizeof(TraceContext)); ctx-trace_id get_trace_id(); ctx-span_id generate_span_id(); ctx-parent_span_id 0; ctx-name name; clock_gettime(CLOCK_MONOTONIC, ctx-start); LOG_DEBUG(TRACE START: trace%llu span%llu name%s, ctx-trace_id, ctx-span_id, name); return ctx; } ​ /** * brief 结束追踪 */ void trace_end(TraceContext* ctx) { struct timespec end; clock_gettime(CLOCK_MONOTONIC, end); long elapsed_ms (end.tv_sec - ctx-start.tv_sec) * 1000 (end.tv_nsec - ctx-start.tv_nsec) / 1000000; LOG_DEBUG(TRACE END: trace%llu span%llu duration%ldms, ctx-trace_id, ctx-span_id, elapsed_ms); free(ctx); } ​ /* 使用示例: 追踪CAN处理延迟 */ int handle_can_frame(const HalCanFrame* frame) { TraceContext* trace trace_start(can_handler); /* ... 业务逻辑 ... */ trace_end(trace); return 0; } ​ #endif6.2 调试检查清单# 调试检查清单 (Debugging Checklist) ​ ## 阶段1: 现象确认 - [ ] 问题是什么(一句话描述) - [ ] 何时发生(时间点/运行时长) - [ ] 触发条件(特定操作/特定数据) - [ ] 复现率(必现/偶现/概率) - [ ] 影响范围(单模块/全系统) ​ ## 阶段2: 数据采集 - [ ] 系统日志 (syslog/dmesg) - [ ] 应用日志 (ERROR/WARN/DEBUG级别) - [ ] Metrics指标 (CPU/内存/网络/IO) - [ ] Core dump (如果coredump) - [ ] 网络抓包 (tcpdump) - [ ] 系统状态 (top/htop/iotop) ​ ## 阶段3: 假设验证 - [ ] 列出可能原因 (至少3个) - [ ] 设计验证实验 - [ ] 隔离变量法 (一次改变一个) - [ ] 二分法定位 (排除法) ​ ## 阶段4: 根因定位 - [ ] 确认根本原因 - [ ] 评估影响范围 - [ ] 记录分析过程 ​ ## 阶段5: 修复验证 - [ ] 代码审查 - [ ] 单元测试覆盖 - [ ] 压力测试验证 - [ ] 灰度发布 - [ ] 监控告警配置七、如何写文档四层文档体系7.1 文档金字塔┌─────────────────────────────────────────────────────────────────────────────┐ │ 四层文档体系 │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ 第1层: 架构文档 (给所有人) │ │ │ │ • 系统架构图 • 模块关系 • 数据流 • 部署图 │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ 第2层: 模块文档 (给相关开发者) │ │ │ │ • 模块职责 • 接口定义 • 依赖关系 • 配置说明 │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ 第3层: 代码文档 (给维护者) │ │ │ │ • Doxygen注释 • 设计模式说明 • 算法复杂度 • 边界条件 │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ 第4层: 运维文档 (给运维人员) │ │ │ │ • 部署指南 • 配置清单 • 监控指标 • 故障排查手册 │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘7.2 Doxygen注释规范/** * file can_manager.c * brief CAN总线管理器实现 * author 张三 zhangsancompany.com * date 2024-01-15 * version 2.0.0 * * details * 本模块负责管理3路CAN总线(MCP2515)的收发操作。 * 支持SocketCAN标准接口波特率可配置125k-1Mbps。 * * section example 使用示例 * code * CanManager* mgr can_manager_create(); * can_manager_open(mgr, CAN_PORT_0, 250000); * * HalCanFrame frame {.can_id 0x123, .can_dlc 8}; * can_manager_send(mgr, frame); * endcode * * see hal_can.h */ ​ /** * defgroup CAN_CANFD CAN FD配置 * brief CAN FD相关宏定义 * { */ #define CAN_FD_SUPPORTED 1 /** 是否支持CAN FD */ #define CAN_FD_MAX_DLC 64 /** CAN FD最大数据长度 */ /** } */ ​ /** * struct CanManager * brief CAN管理器结构体 * * 封装CAN设备的所有操作和状态。 */ typedef struct CanManager { int sockfds[3]; /** SocketCAN套接字数组(0/1/2) */ int is_open[3]; /** 各接口打开状态 */ char ifnames[3][8]; /** 接口名称(can0/can1/can2) */ uint32_t rx_count[3]; /** 接收计数 */ uint32_t tx_count[3]; /** 发送计数 */ uint32_t error_count[3]; /** 错误计数 */ pthread_mutex_t mutex; /** 互斥锁 */ } CanManager; ​ /** * brief 打开CAN设备 * param mgr CAN管理器指针 * param port CAN端口(0-2) * param baudrate 波特率(125000,250000,500000,1000000) * return 0成功, -1失败 * * pre mgr ! NULL * pre port 0 port 3 * pre baudrate in {125000,250000,500000,1000000} * * post mgr-is_open[port] 1 * * complexity O(1) * * exception 返回-1表示打开失败可通过errno获取详细错误 * * note 打开前会先关闭已有连接 * warning 必须在root权限下运行 * * see can_manager_close */ int can_manager_open(CanManager* mgr, int port, int baudrate) { /* 实现... */ }7.3 架构决策记录模板# ADR-001: CAN通信方案选型 ​ ## 状态 ✅ 已采纳 | ⚠️ 提议中 | ❌ 已废弃 ​ ## 上下文 需要支持3路CAN总线每路250kbps要求实时性1ms丢帧率0.01%。 ​ ## 决策 采用Linux内核SocketCAN框架。 ​ ## 理由 1. 内核原生支持稳定可靠 2. 与标准Socket API一致学习成本低 3. 支持多路并发 4. 已有成熟工具(candump, cansend) ​ ## 后果 - 正面: 开发周期从4周缩短到1周 - 负面: 需要Linux 3.2内核 ​ ## 替代方案 | 方案 | 优点 | 缺点 | |-----|------|------| | 直接操作/dev/can | 无依赖 | 开发工作量大 | | libcan库 | 封装完善 | 额外依赖 | ​ ## 参考资料 - kernel.org/doc/html/latest/networking/can.html - https://github.com/linux-can/can-utils八、团队协作流程8.1 并行开发模型┌─────────────────────────────────────────────────────────────────────────────┐ │ 并行开发时间线 │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ 时间 ───────────────────────────────────────────────────────────→ │ │ │ │ 团队A: ┌──────契约定义──────┐ │ │ │ (第1-3天) │ │ │ └────────┬───────────┘ │ │ │ │ │ ▼ │ │ 团队A: ┌────────────────────────┐ │ │ (上层) │ 实现上层业务逻辑 │ │ │ │ (使用Mock) │ │ │ └────────────────────────┘ │ │ │ │ 团队B: ┌────────────────────────┐ │ │ (底层) │ 实现底层驱动 │ │ │ │ (实现契约) │ │ │ └────────────────────────┘ │ │ │ │ 契约测试 │ │ ┌─────────────┐ │ │ │ 集成测试 │ │ │ └─────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘8.2 代码审查检查清单# 代码审查检查清单 ​ ## 功能正确性 - [ ] 代码是否满足需求 - [ ] 边界条件是否处理 - [ ] 错误路径是否覆盖 ​ ## 设计质量 - [ ] 是否符合单一职责 - [ ] 依赖方向是否正确 - [ ] 接口是否最小化 ​ ## 性能 - [ ] 是否有不必要的内存分配 - [ ] 锁粒度是否合理 - [ ] 是否有潜在的性能瓶颈 ​ ## 可测试性 - [ ] 是否易于单元测试 - [ ] 依赖是否可以Mock - [ ] 是否有调试日志 ​ ## 安全性 - [ ] 输入是否验证 - [ ] 是否有缓冲区溢出风险 - [ ] 资源是否正确释放 ​ ## 文档 - [ ] 复杂逻辑是否有注释 - [ ] 公共API是否有文档 - [ ] 架构决策是否有记录九、总结技术专家的核心能力/** * brief 技术专家的七大核心能力 * * 1. 抽象能力 - 从具体问题中提炼通用模型 * 2. 分解能力 - 将复杂系统拆解为可管理模块 * 3. 权衡能力 - 在多个方案中找到最优解 * 4. 沟通能力 - 用非技术人员能懂的语言解释技术 * 5. 预见能力 - 预见变化设计可扩展架构 * 6. 复盘能力 - 从失败中学习持续改进 * 7. 传承能力 - 沉淀知识培养新人 */ ​ /** * brief 总结 * * “完美的架构不是一次设计出来的而是随着对问题域理解的深入 * 不断演化的结果。追求的不是最完美的架构而是最适合当前团队、 * 当前业务阶段、当前技术约束的架构。 * * 方法论是 * 1. 【先定义契约后实现代码】- 契约测试保证模块间一致性 * 2. 【先写测试后写功能】- TDD驱动设计 * 3. 【先跑通链路后优化细节】- 快速验证核心价值 * 4. 【先统一规范后自由发挥】- 规范保证团队效率 * * 最重要的是让架构服务于业务而不是让业务服务于架构。” */推荐阅读书籍核心观点适用场景《架构整洁之道》依赖规则、边界清晰系统设计《领域驱动设计》统一语言、限界上下文复杂业务《设计模式》可复用面向对象代码设计《重构》持续改进、代码坏味代码维护《Google软件测试之道》测试金字塔质量保障