⚡

代码注释模式Skill code-annotation-patterns

此技能专注于在代码中添加结构化元数据、标签和标记的注释模式，以支持AI辅助的软件开发工作流。它涵盖多种注释格式、语义标签和开发工具集成，帮助提升代码可维护性、安全性和性能，适用于技术债务跟踪、安全注解、性能优化等场景。关键词：代码注释、AI开发、结构化元数据、语义标签、开发工具集成、技术债务、安全分析、性能瓶颈、可访问性、测试覆盖。

架构设计 0 次安装 0 次浏览 更新于 3/25/2026

名称: 代码注释模式 描述: 在代码中使用结构化元数据、标签和标记进行注释，以支持AI辅助的开发工作流。涵盖注释格式、语义标签和与开发工具的集成。 允许工具:

  • 读取
  • 写入
  • 编辑
  • Bash
  • Grep
  • Glob

AI开发的代码注释模式

用于支持AI辅助开发工作流的结构化元数据注释的高级模式。

注释类别

技术债务标记

用于跟踪技术债务的结构化注释：

/**
 * @ai-技术债务
 * @类别: 架构
 * @严重性: 高
 * @工作量: 2-3天
 * @影响: 可维护性, 性能
 *
 * 此服务类已增长到1500+行，违反了单一职责原则。应拆分为：
 * - UserAuthService（认证逻辑）
 * - UserProfileService（档案管理）
 * - UserPreferencesService（设置/偏好）
 *
 * 阻塞新功能：用户角色管理(#234)，单点登录集成(#245)
 */
class UserService {
  // 实现...
}

严重性级别：

  • 关键：安全漏洞、数据丢失风险
  • 高：显著的可维护性或性能问题
  • 中：代码质量问题、测试缺口
  • 低：小改进、可有可无

安全注释

# @ai-安全
# @风险级别: 高
# @cwe: CWE-89 (SQL注入)
# @缓解措施: 使用参数化查询
#
# 安全警告：此函数动态构建SQL查询。
# 虽然输入经过验证，但参数化查询会更安全。
# 当前验证正则表达式：^[a-zA-Z0-9_]+$
# TODO(ai/安全): 迁移到SQLAlchemy ORM或使用参数化查询

def get_user_by_username(username: str):
    # 使用字符串格式化的当前实现
    query = f"SELECT * FROM users WHERE username = '{username}'"

性能注释

/**
 * @ai-性能
 * @复杂度: O(n²)
 * @瓶颈: true
 * @性能分析数据: 当n > 100时，占请求时间的45%
 * @优化目标: O(n log n) 或更好
 *
 * 此嵌套循环是大数据集的主要性能瓶颈。性能分析显示：
 * - n=10: 5ms 平均
 * - n=100: 120ms 平均
 * - n=1000: 11s 平均（不可接受）
 *
 * 优化方法：
 * 1. 排序 + 二分搜索: O(n log n) - 预计95%改进
 * 2. 哈希表: O(n) - 最佳性能但内存使用较高
 * 3. 数据库级优化: 将逻辑移至SQL查询
 */
public List<Match> findMatches(List<Item> items) {
    // O(n²) 实现
}

可访问性注释

/**
 * @ai-可访问性
 * @wcag级别: AA
 * @合规状态: 部分
 * @问题:
 *   - 图标按钮缺少ARIA标签
 *   - 颜色对比不足 (3.2:1, 需要4.5:1)
 *   - 键盘导航不完整
 *
 * 组件需要可访问性改进以满足WCAG 2.1级别AA。
 * 审计完成: 2025-12-04
 * 阻塞: 公共部门部署（要求AA合规）
 */
export function SearchBar() {
  // 带有部分可访问性支持的实现
}

测试注释

// @ai-测试
// @覆盖率: 45%
// @覆盖率目标: 80%
// @缺少测试:
//   - 边缘情况: nil指针处理
//   - 边缘情况: 并发访问场景
//   - 集成: 数据库事务回滚
//
// 测试覆盖率低于目标。优先领域：
// 1. 错误处理路径（当前未测试）
// 2. 并发访问（在PR审查中识别出竞态条件）
// 3. 数据库边缘情况（事务边界）

func ProcessOrder(order *Order) error {
    // 测试覆盖率不完整的实现
}

语义标签

变更影响标签

/**
 * @ai-变更影响
 * @破坏性变更: true
 * @影响:
 *   - API消费者（公共方法签名更改）
 *   - 数据库迁移（需要模式更新）
 *   - 依赖服务（合同修改）
 *
 * 此更改修改了公共API合同。迁移指南：
 * 1. 更新API客户端以使用新参数格式
 * 2. 运行迁移脚本：./scripts/migrate_v2_to_v3.sh
 * 3. 更新环境变量（需要NEW_API_KEY）
 *
 * 向后兼容性：支持到v4.0.0 (2026-06-01)
 */

依赖标签

# @ai-依赖
# @外部服务: PaymentAPI
# @故障模式: 优雅降级
# @回退: 离线支付队列
# @sla: 99.9% 正常运行时间
# @超时: 5000ms
#
# 此函数依赖于外部支付服务。故障处理：
# - 超时：重试队列，通知用户延迟处理
# - 服务宕机：批量处理队列，本地存储交易
# - 无效响应：记录错误，回滚事务，通知监控
#
# 断路器：连续5次故障后打开，30秒后半开

async def process_payment(transaction: Transaction) -> PaymentResult:
    # 具有外部服务依赖的实现

配置标签

/// @ai-配置
/// @环境变量:
///   - DATABASE_URL (必需)
///   - REDIS_URL (可选，回退到内存缓存)
///   - LOG_LEVEL (可选，默认: "info")
/// @配置文件: config/production.yaml
/// @秘密:
///   - API_SECRET_KEY (必须32+字符)
///   - JWT_PRIVATE_KEY (RSA 2048位最小)
///
/// 配置加载顺序：
/// 1. 环境变量（最高优先级）
/// 2. config/{environment}.yaml 文件
/// 3. 默认值（最低优先级）

pub struct AppConfig {
    // 配置字段
}

注释格式

内联注释

用于单行或小上下文：

// @ai-模式: 单例
// @ai-线程安全: 非线程安全，仅在单线程上下文中使用
const cache = createCache();

块注释

用于复杂上下文：

"""
@ai-模式: 工厂模式
@ai-创建模式: true
@ai-原理:
  此处使用工厂模式因为：
  1. 需要支持多个数据库后端（PostgreSQL, MySQL, SQLite）
  2. 配置决定实例化哪个实现
  3. 允许轻松添加新后端而不修改客户端代码

@ai-可扩展性:
  添加新数据库后端：
  1. 实现DatabaseBackend接口
  2. 在BACKEND_REGISTRY字典中注册
  3. 在config/database.yaml中添加配置映射

示例用法在docs/database-backends.md
"""
class DatabaseFactory:
    # 实现

结构化元数据

/**
 * @ai-元数据 {
 *   "模式": "观察者",
 *   "订阅者": ["LoggingService", "MetricsService", "AuditService"],
 *   "事件类型": ["user.created", "user.updated", "user.deleted"],
 *   "异步": true,
 *   "保证交付": false
 * }
 *
 * 使用观察者模式的事件总线，用于服务间的松耦合。
 * 事件以异步方式发布，采用即发即弃语义（无交付保证）。
 * 对于需要保证交付的关键事件，请使用消息队列。
 */
class EventBus {
  // 实现
}

语言特定模式

TypeScript/JavaScript

/**
 * @ai-钩子使用
 * @react-钩子: [useState, useEffect, useCallback, useMemo]
 * @依赖项: {useCallback: [data, filter], useMemo: [data], useEffect: [id]}
 * @优化: useMemo防止重渲染时昂贵重新计算
 *
 * 此组件使用React钩子进行状态和副作用。依赖数组
 * 被精心管理以防止不必要的重渲染和无限循环。
 *
 * @ai-性能注意:
 * - useMemo缓存过滤结果（将每次渲染的过滤从O(n)减少到数据更改时一次）
 * - useCallback记忆事件处理器（防止子组件重渲染）
 */
export function DataTable({ data, id }: Props) {
  const [filter, setFilter] = useState('');

  const handleFilter = useCallback((value: string) => {
    setFilter(value);
  }, [data, filter]); // @ai-依赖注意: 闭包需要两者

  const filteredData = useMemo(() => {
    return data.filter(item => item.name.includes(filter));
  }, [data]); // @ai-优化: 仅在数据更改时重新计算

  // 实现...
}

Python

# @ai-装饰器栈
# @装饰器: [retry, cache, log_execution, validate_auth]
# @执行顺序: validate_auth -> log_execution -> cache -> retry -> 函数
#
# 装饰器执行顺序重要：
# 1. validate_auth: 必须首先运行以防止未经授权的缓存命中
# 2. log_execution: 认证后日志记录，缓存前跟踪所有尝试
# 3. cache: 日志记录后缓存以避免记录缓存命中
# 4. retry: 最内层重试实际函数，而非认证/日志记录

@validate_auth(roles=["admin", "operator"])
@log_execution(level="INFO")
@cache(ttl=300, key_func=lambda args: f"user:{args[0]}")
@retry(max_attempts=3, backoff=exponential)
def get_user_profile(user_id: int) -> UserProfile:
    """
    @ai-缓存策略: 基于时间 (TTL=300s)
    @ai-失效: 用户更新事件时手动失效
    @ai-缓存键: user:{user_id}
    """
    # 实现

Go

// @ai-并发
// @模式: 工作者池
// @工作者: 10（可通过WORKER_POOL_SIZE配置）
// @通道缓冲区: 100
// @背压处理: 缓冲区满时阻塞
//
// 此实现工作者池模式用于并发处理。
// 工作者在服务器初始化时启动，并在服务器生命周期内保持活动（无动态扩展）。
//
// @ai-监控:
//   - 指标: worker_pool_queue_depth（当前通道缓冲区大小）
//   - 指标: worker_pool_processing_time（直方图）
//   - 警报: 队列深度 > 80 持续 >5分钟（增加工作者）

type WorkerPool struct {
    workers   int
    jobQueue  chan Job
    resultCh  chan Result
    // 字段...
}

Rust

/// @ai-生命周期注解
/// @生命周期: ['a, 'b]
/// @不变式:
///   - 'a 必须比 'b 长（解析器必须比输入存活更久）
///   - 输出引用绑定到 'a（只要输入存活就安全）
///
/// 生命周期关系：
/// - Parser<'a> 借用输入 'a
/// - Output<'a> 包含对输入的引用（受 'a 限制）
/// - 临时分配使用 'b（限于解析期间）
///
/// @ai-安全:
/// 这些生命周期约束通过确保输入缓冲区比所有从其派生的引用存活更久来防止悬空引用。

pub struct Parser<'a> {
    input: &'a str,
    // 字段...
}

与工具集成

IDE集成

注释可由IDE插件提取：

# 提取所有AI注释
rg "@ai-\\w+" --type ts --json | jq '.text'

# 查找安全相关注释
rg "@ai-安全" -A 10

# 查找性能瓶颈
rg "@瓶颈: true" --type java

静态分析

自定义链接器可强制执行注释标准：

// 示例：ESLint规则强制在认证函数上使用@ai-安全
module.exports = {
  rules: {
    'require-security-annotation': {
      create(context) {
        return {
          FunctionDeclaration(node) {
            if (node.id.name.includes('auth') || node.id.name.includes('Auth')) {
              // 检查 @ai-安全 注释
            }
          }
        };
      }
    }
  }
};

文档生成

提取注释以生成文档：

# doc_generator.py
import re
from pathlib import Path

def extract_ai_annotations(file_path):
    """从文件提取所有 @ai-* 注释"""
    with open(file_path) as f:
        content = f.read()

    pattern = r'@ai-(\\w+):\\s*(.+)'
    return re.findall(pattern, content)

# 从注释生成Markdown文档

注释最佳实践

一致性

在整个代码库中使用一致的注释格式：

// ✅ 良好 - 一致格式
// @ai-模式: 策略
// @ai-替代方案: [模板方法, 状态模式]

// @ai-模式: 观察者
// @ai-替代方案: [事件发射器, 发布/订阅]

// ❌ 不良 - 不一致格式
// @ai-模式: 策略（替代方案: 模板方法, 状态）
// 模式: 观察者 | 替代方案: 事件发射器, 发布/订阅

完整性

包含所有相关元数据：

# ✅ 良好 - 完整上下文
# @ai-安全
# @风险级别: 高
# @cwe: CWE-79 (XSS)
# @输入清理: 应用HTML编码
# @输出编码: UTF-8
# @已测试: 测试/安全/xss_test.py中的XSS测试套件

# ❌ 不良 - 不完整
# @ai-安全
# 此处有安全风险

可维护性

保持注释最新：

// ✅ 良好 - 日期化和跟踪
// @ai-技术债务
// @添加: 2025-12-04
// @审查: 2025-12-04
// @下次审查: 2026-01-04

// ❌ 不良 - 陈旧和过时
// @ai-技术债务
// TODO: 最终修复此问题

反模式

不要

❌ 过度注释明显代码

// @ai-模式: 变量声明
const user = getUser(); // 不良 - 明显

❌ 使用注释代替修复代码

# @ai-技术债务: 这是糟糕的代码
# @ai-安全: 有漏洞
# @ai-性能: 慢
# 不良 - 直接修复代码！

❌ 不一致的标签命名

// @AI-PATTERN vs @ai-模式 vs @aiPattern
// 使用一致命名

要做

✅ 注释复杂或非明显模式

/// @ai-模式: 类型状态
/// @ai-编译时安全: true
///
/// 使用类型状态模式在编译时强制执行协议状态机。
/// 不可能的状态在类型系统中无法表示。

✅ 提供可操作信息

/**
 * @ai-技术债务
 * @操作: 提取UserValidator类
 * @受影响文件: [UserService.java, UserController.java, UserTest.java]
 * @工作量: 3-4小时
 * @优先级: 中
 */

✅ 链接到外部资源

# @ai-算法: Dijkstra最短路径
# @参考: https://en.wikipedia.org/wiki/Dijkstra%27s_algorithm
# @论文: "A Note on Two Problems in Connexion with Graphs" (1959)
# @优化: 使用二叉堆实现O((V+E) log V)复杂度

相关技能

  • 笔记基础
  • 文档链接

资源