powershell-module-architect

PowerShell 模块架构师

用途

提供 PowerShell 模块设计和架构方面的专业知识，专注于创建结构清晰、可复用且易于维护的 PowerShell 模块。重点关注模块架构、函数设计、跨版本兼容性，以及企业 PowerShell 环境中的配置文件优化。

适用场景

• 将零散脚本转换为结构清晰、可复用的模块
• 设计模块架构，并区分公有函数和私有函数
• 创建跨版本兼容的模块（PowerShell 5.1 和 7+）
• 优化 PowerShell 配置文件，以缩短加载时间
• 构建具有适当参数验证的高级函数

快速开始

在以下情况下调用此技能：

• 将零散脚本转换为结构清晰、可复用的模块
• 设计模块架构，并区分公有函数和私有函数
• 创建跨版本兼容的模块（PowerShell 5.1 和 7+）
• 优化 PowerShell 配置文件，以缩短加载时间
• 构建具有适当参数验证的高级函数

以下情况请勿调用：

• 不会复用的简单一次性脚本（使用 powershell-5.1-expert 或 powershell-7-expert）
• 已有结构良好的模块，只需添加功能（使用相关领域技能）
• UI 开发（改用 powershell-ui-architect）
• 安全加固（改用 powershell-security-hardening）

决策框架

何时创建模块

场景	建议
3 个或更多相关函数	创建模块
需要跨团队共享	创建模块 + 清单
一次性自动化	保留为脚本
复杂的参数集	在模块中使用高级函数
需要版本兼容性	使用带兼容层的模块

模块结构决策

Script Organization Need
│
├─ Few related functions (3-10)?
│  └─ Single .psm1 with inline functions
│
├─ Many functions (10+)?
│  └─ Dot-source pattern (Public/Private folders)
│
├─ Publishing to gallery?
│  └─ Full manifest + tests + docs
│
└─ Team collaboration?
   └─ Git repo + CI/CD + Pester tests

核心工作流：将脚本转换为模块

用例： 将 10-50 个零散的 .ps1 脚本重构为有序的模块

第 1 步：分析

# Inventory existing scripts
$scripts = Get-ChildItem -Path ./scripts -Filter *.ps1 -Recurse

# Analyze function signatures
foreach ($script in $scripts) {
    $content = Get-Content $script.FullName -Raw
    $functions = [regex]::Matches($content, 'function\s+(\S+)')
    
    Write-Host "$($script.Name): $($functions.Count) functions"
}

# Expected output:
# AD-UserManagement.ps1: 12 functions
# AD-GroupManagement.ps1: 8 functions
# Common-Helpers.ps1: 15 functions (candidates for Private/)

第 2 步：设计模块结构

# Create module skeleton
$moduleName = "Organization.ActiveDirectory"
$modulePath = "./modules/$moduleName"

New-Item -Path "$modulePath/Public" -ItemType Directory -Force
New-Item -Path "$modulePath/Private" -ItemType Directory -Force
New-Item -Path "$modulePath/Tests" -ItemType Directory -Force
New-Item -Path "$modulePath/$moduleName.psm1" -ItemType File -Force
New-Item -Path "$modulePath/$moduleName.psd1" -ItemType File -Force

第 3 步：对函数分类

Public functions (exported to users):
  ├─ Get-OrgADUser
  ├─ New-OrgADUser
  ├─ Set-OrgADUser
  ├─ Remove-OrgADUser
  └─ ... (user-facing functions)

Private functions (internal helpers):
  ├─ _ValidateDomainConnection
  ├─ _BuildDistinguishedName
  ├─ _ConvertToCanonicalName
  └─ ... (utility functions)

第 4 步：实现模块文件

# Organization.ActiveDirectory.psm1

# Dot-source Private functions first
$Private = @(Get-ChildItem -Path $PSScriptRoot\Private\*.ps1 -ErrorAction SilentlyContinue)
foreach ($import in $Private) {
    try {
        . $import.FullName
    } catch {
        Write-Error "Failed to import private function $($import.FullName): $_"
    }
}

# Dot-source Public functions
$Public = @(Get-ChildItem -Path $PSScriptRoot\Public\*.ps1 -ErrorAction SilentlyContinue)
foreach ($import in $Public) {
    try {
        . $import.FullName
    } catch {
        Write-Error "Failed to import public function $($import.FullName): $_"
    }
}

# Export Public functions explicitly
Export-ModuleMember -Function $Public.BaseName

第 5 步：创建模块清单

# Generate manifest
$manifestParams = @{
    Path              = "$modulePath/$moduleName.psd1"
    RootModule        = "$moduleName.psm1"
    ModuleVersion     = '1.0.0'
    Author            = 'IT Team'
    CompanyName       = 'Organization'
    Description       = 'Active Directory management functions'
    PowerShellVersion = '5.1'  # Minimum version
    FunctionsToExport = @(
        'Get-OrgADUser',
        'New-OrgADUser',
        'Set-OrgADUser',
        'Remove-OrgADUser'
    )
    VariablesToExport = @()
    AliasesToExport   = @()
}
New-ModuleManifest @manifestParams

第 6 步：添加 Pester 测试

# Tests/Module.Tests.ps1
BeforeAll {
    Import-Module "$PSScriptRoot/../Organization.ActiveDirectory.psd1" -Force
}

Describe "Organization.ActiveDirectory Module" {
    It "Exports expected functions" {
        $commands = Get-Command -Module Organization.ActiveDirectory
        $commands.Count | Should -BeGreaterThan 0
    }
    
    It "Has valid module manifest" {
        $manifest = Test-ModuleManifest -Path "$PSScriptRoot/../Organization.ActiveDirectory.psd1"
        $manifest.Version | Should -Be '1.0.0'
    }
}

Describe "Get-OrgADUser" {
    It "Accepts Identity parameter" {
        { Get-OrgADUser -Identity "testuser" -WhatIf } | Should -Not -Throw
    }
}

快速参考：高级函数模板

function Get-OrgUser {
    <#
    .SYNOPSIS
        Retrieves Active Directory user by name.
    
    .DESCRIPTION
        Queries Active Directory for user object and returns detailed properties.
    
    .PARAMETER Name
        The username or SamAccountName to search for.
    
    .EXAMPLE
        Get-OrgUser -Name "jdoe"
        
        Returns all properties for user jdoe.
    
    .EXAMPLE
        "jdoe", "asmith" | Get-OrgUser
        
        Retrieves multiple users via pipeline.
    #>
    [CmdletBinding()]
    param(
        [Parameter(Mandatory, ValueFromPipeline)]
        [ValidateNotNullOrEmpty()]
        [string]$Name
    )
    
    process {
        Get-ADUser -Identity $Name -Properties *
    }
}

集成模式

powershell-5.1-expert

• 交接： 模块架构设计完成 → 由 5.1 专家实现 Windows 专用函数
• 协作： 在设计模块结构时考虑 5.1 兼容性

powershell-7-expert

• 交接： 模块结构已定义 → 由 7 专家添加现代语法优化
• 协作： 使用版本检测实现双模式函数

windows-infra-admin

• 交接： 模块架构 → Windows 管理员实现特定领域逻辑
• 共同职责： Active Directory、GPO、DNS 模块函数

azure-infra-engineer

• 交接： 模块模式 → Azure 工程师构建云自动化模块
• 集成： 结合本地环境和 Azure 的跨云模块

升级处理的警示信号

观察到的情况	操作
单个模块中有 100 个以上函数	考虑拆分为子模块
复杂的跨版本问题	咨询 powershell-5.1 和 7 专家
配置文件加载性能低于 1 秒	应用延迟加载模式
涉及安全敏感操作	请 powershell-security-hardening 参与处理

更多资源

• 详细技术参考： 请参阅 REFERENCE.md

  • 配置文件优化工作流
  • 模块清单模板
  • 动态参数模式

• 代码示例和模式： 请参阅 EXAMPLES.md

  • 反模式（单体文件、缺少帮助信息）
  • 跨版本兼容模式
  • 高级参数验证