名称：文档链接描述：用于在代码和文档之间创建双向链接。覆盖链接模式、文档引用、跨工件的上下文保持，以及维护代码和文档之间的同步。允许工具：

读取
写入
编辑
Bash
Grep
Glob

文档链接

为AI辅助开发创建和维护代码和文档之间的双向链接。

双向链接

代码 → 文档

从代码链接到相关文档：

/**
 * 实现认证流程，描述于：
 * @doc docs/architecture/authentication.md#oauth-flow
 * @api-spec api/openapi.yaml#/components/securitySchemes/oauth2
 * @decision-record docs/decisions/003-oauth-provider.md
 *
 * 相关端点：
 * - POST /auth/login (登录初始化)
 * - GET /auth/callback (OAuth回调)
 * - POST /auth/refresh (令牌刷新)
 */
export class AuthenticationService {
  // 实现
}

文档 → 代码

从文档链接到实现代码：

# 认证流程

我们的OAuth 2.0认证流程实现在：

- 主要逻辑：`src/services/AuthenticationService.ts`
- 路由：`src/routes/auth.ts:15-45`
- 中间件：`src/middleware/auth.ts:78`
- 测试：`tests/integration/auth.test.ts`

另见：
- 数据库模式：`migrations/003_create_users.sql`
- 配置：`config/auth.yaml`

链接格式

绝对链接

# @doc /docs/database/migrations.md#schema-versioning
# 从仓库根目录的完整路径

相对链接

// @doc ../../../docs/api/rest-endpoints.md#user-endpoints
// 相对于当前文件

行特定链接

// @impl service/user_service.go:145-178
// 链接到特定行范围

锚点链接

/// @doc architecture.md#data-flow-diagram
/// 通过锚点链接到特定部分

文档类型

架构文档

/**
 * @arch-doc docs/architecture/system-overview.md
 * @component-diagram docs/diagrams/user-service.svg
 * @sequence-diagram docs/diagrams/login-flow.puml
 *
 * 此服务是用户管理子系统的一部分。
 * 参见架构文档以了解组件交互和数据流。
 */
class UserService {
  // 实现
}

API文档

# @api-doc docs/api/rest-api.md#POST-/users
# @openapi-spec api/openapi.yaml#/paths/~1users/post
# @example docs/examples/create-user.md
#
# 创建用户的REST端点。API合约定义在OpenAPI规范中。
# 请求/响应格式的更改必须更新代码和规范。

@app.post("/users")
async def create_user(user: UserCreate) -> User:
    """
    @request-example:
      POST /users
      {
        "email": "user@example.com",
        "name": "John Doe"
      }

    @response-example:
      201 Created
      {
        "id": 123,
        "email": "user@example.com",
        "name": "John Doe",
        "created_at": "2025-12-04T10:00:00Z"
      }
    """
    # 实现

决策记录

/**
 * @decision-record docs/decisions/005-caching-strategy.md
 *
 * 决策：使用Redis进行缓存而不是内存缓存
 * 理由：需要分布式缓存以支持水平扩展
 * 日期：2025-11-15
 *
 * 这实现了ADR-005中定义的缓存策略。
 * 缓存失效规则：
 * 1. 基于时间：5分钟TTL
 * 2. 基于事件：在user.updated事件时失效
 * 3. 手动：管理员可以通过/admin/cache/clear清除缓存
 */
public class CacheService {
    // 遵循决策记录的实现
}

测试文档

// @test-doc docs/testing/integration-tests.md#database-tests
// @test-data fixtures/users.json
// @test-cases tests/integration/user_test.go
//
// 集成测试使用Docker容器用于PostgreSQL。
// 测试数据在每次测试前从夹具加载。
// 参见测试文档以获取设置说明。

func TestUserRepository(t *testing.T) {
    // 测试实现
}

运行手册链接

# @runbook docs/runbooks/incident-response.md#database-failover
# @monitoring dashboard/database-health
# @alerts alerts/database-connection-pool
#
# 数据库连接池监控和故障转移逻辑。
# 如果池耗尽警报触发，请遵循运行手册进行缓解步骤。

class DatabaseConnectionPool:
    """
    @metric connection_pool_active (gauge)
    @metric connection_pool_idle (gauge)
    @metric connection_pool_wait_time (histogram)

    警报阈值：
    - connection_pool_active > 90% 最大连接数持续5分钟
    - connection_pool_wait_time p95 > 1000ms
    """
    # 实现

交叉引用模式

问题/工单引用

/**
 * @issue https://github.com/org/repo/issues/1234
 * @pr https://github.com/org/repo/pull/1245
 * @jira PROJ-567
 *
 * 实现用户故事PROJ-567：实时通知系统
 * 参见问题#1234以获取需求讨论
 * 参见PR #1245以获取实现审查和反馈
 */
class NotificationService {
  // 实现
}

Wiki/Confluence链接

# @wiki https://wiki.company.com/display/ENG/Data+Pipeline
# @confluence https://company.atlassian.net/wiki/spaces/ARCH/pages/123456
#
# 数据管道架构记录在公司wiki中。
# 这实现了ETL管道的提取阶段。

class DataExtractor:
    # 实现

外部资源

/// @rfc https://tools.ietf.org/html/rfc7519
/// @spec https://openid.net/specs/openid-connect-core-1_0.html
/// @tutorial https://auth0.com/docs/secure/tokens/json-web-tokens
///
/// JWT实现遵循RFC 7519规范。
/// 支持OIDC核心规范中的OpenID Connect扩展。

pub struct JwtToken {
    // 实现
}

同步策略

自动化链接验证

验证文档链接的脚本：

#!/bin/bash
# validate-doc-links.sh

# 从代码中提取所有@doc引用
grep -r "@doc " src/ | while read -r line; do
  doc_path=$(echo "$line" | sed -n 's/.*@doc \([^[:space:]]*\).*/\1/p')
  file_path=$(echo "$doc_path" | cut -d'#' -f1)

  if [ ! -f "$file_path" ]; then
    echo "ERROR: 断裂的文档链接：$doc_path"
    echo "  引用在：$line"
  fi
done

文档覆盖率

跟踪哪些代码有文档链接：

# doc-coverage.py
import re
from pathlib import Path

def has_doc_link(file_path):
    """检查文件是否包含@doc注解"""
    with open(file_path) as f:
        content = f.read()
    return '@doc' in content or '@api-doc' in content

# 计算覆盖率
source_files = list(Path('src').rglob('*.py'))
with_docs = [f for f in source_files if has_doc_link(f)]
coverage = len(with_docs) / len(source_files) * 100

print(f"文档链接覆盖率：{coverage:.1f}%")

反向链接跟踪

在文档中维护反向索引：

# 认证文档

## 被引用者

此文档被以下代码文件引用：

- `src/services/AuthenticationService.ts:15` - 主要认证逻辑
- `src/middleware/auth.ts:34` - 认证中间件
- `src/routes/auth.ts:8` - 认证路由

<!-- 自动生成：请勿手动编辑 -->
<!-- 生成者：scripts/update-doc-references.sh -->

链接维护

自动化更新

Git预提交钩子以检查文档链接：

#!/bin/bash
# .git/hooks/pre-commit

echo "验证文档链接..."

# 检查断裂的@doc链接
broken_links=$(grep -r "@doc " src/ | while read -r line; do
  doc_path=$(echo "$line" | sed -n 's/.*@doc \([^[:space:]]*\).*/\1/p')
  file_path=$(echo "$doc_path" | cut -d'#' -f1)

  if [ ! -f "$file_path" ]; then
    echo "$line"
  fi
done)

if [ -n "$broken_links" ]; then
  echo "错误：发现断裂的文档链接："
  echo "$broken_links"
  exit 1
fi

链接弃用

标记过时的链接：

/**
 * @doc docs/old-approach.md [已弃用：参见docs/new-approach.md]
 * @doc-current docs/new-approach.md
 *
 * 此实现正在迁移到新方法。
 * 旧文档在过渡期间保留供参考。
 * 迁移截止日期：2026-01-01
 */

版本化文档

链接到特定文档版本：

# @doc docs/v2/api-reference.md
# @doc-version 2.3.0
#
# 此代码实现API v2.3.0规范。
# 对于v3.0.0更改，参见docs/v3/migration-guide.md

class APIv2Handler:
    # 实现

文档模式

README链接

链接到README以获取模块文档：

// @readme ./README.md
//
// 包userservice提供用户管理功能。
// 参见README.md以获取使用示例和配置选项。

package userservice

示例代码

链接到可运行的示例：

/// @example examples/basic-usage.rs
/// @example-advanced examples/advanced-patterns.rs
///
/// 基本使用示例展示简单CRUD操作。
/// 高级示例演示批处理和事务。

pub struct Repository<T> {
    // 实现
}

教程链接

/**
 * @tutorial docs/tutorials/getting-started.md
 * @tutorial-video https://youtube.com/watch?v=abc123
 * @interactive-demo https://demo.example.com
 *
 * 新到此库？从入门教程开始。
 * 视频教程可供视觉学习者使用。
 */
export class SDK {
  // 实现
}

反模式

不要

❌ 使用脆弱的相对链接

# @doc ../../../../../../../docs/guide.md
# 不好 - 当文件移动时容易中断

❌ 链接到过时的文档

// @doc docs/deprecated-api.md
// 不好 - 应链接到当前文档或标记为已弃用

❌ 创建循环文档依赖

// file1.go
// @doc docs/file2.md

// docs/file2.md 引用 file3.go
// file3.go 引用 file1.go
// 不好 - 循环引用使导航混乱

要做

✅ 使用仓库相对路径

# @doc docs/guide.md
# 好 - 即使当前文件移动也稳定

✅ 保持链接当前

// @doc docs/current-api.md
// @doc-history docs/api-v1.md [已弃用]
// 好 - 清晰哪个是当前

✅ 创建清晰的导航层次

// @doc-parent docs/architecture/overview.md
// @doc-current docs/architecture/auth-service.md
// @doc-related docs/architecture/user-service.md
// 好 - 清晰的层次和关系

集成示例

Markdown文档

# 用户服务

## 实现

用户服务在多个文件中实现：

### 核心逻辑

- [`src/services/UserService.ts`](../src/services/UserService.ts) - 主要服务类
- [`src/models/User.ts`](../src/models/User.ts) - 用户模型
- [`src/repositories/UserRepository.ts`](../src/repositories/UserRepository.ts) - 数据访问

### API层

- [`src/routes/users.ts`](../src/routes/users.ts#L15-L45) - REST端点
- [`src/controllers/UserController.ts`](../src/controllers/UserController.ts) - 请求处理

### 测试

- [`tests/unit/UserService.test.ts`](../tests/unit/UserService.test.ts) - 单元测试
- [`tests/integration/users.test.ts`](../tests/integration/users.test.ts) - 集成测试

OpenAPI/Swagger

# api/openapi.yaml
paths:
  /users:
    post:
      summary: 创建用户
      description: |
        在系统中创建新用户。

        **实现：**
        - 处理器：`src/handlers/users.go:CreateUser`
        - 验证：`src/validators/user.go:ValidateCreate`
        - 数据库：`src/repositories/user_repo.go:Insert`

        **相关文档：**
        - [用户管理指南](../docs/user-management.md)
        - [API认证](../docs/api-auth.md)

JSDoc/TypeDoc

/**
 * 用户认证服务
 *
 * @see {@link ../docs/architecture/auth-flow.md} 以获取认证流程图
 * @see {@link ../docs/api/auth-api.md} 以获取API文档
 *
 * @example
 * ```typescript
 * const auth = new AuthService();
 * const token = await auth.login(username, password);
 * ```
 *
 * @example
 * 参见 {@link ../examples/auth-flow.ts} 以获取完整认证示例
 */
export class AuthService {
  // 实现
}