⚡

PowerShell模块架构师Skill powershell-module-architect

PowerShell 模块架构师技能专注于为企业环境设计、构建和优化结构化、可重用且可维护的 PowerShell 模块。核心内容包括：模块架构设计、公共与私有函数分离、跨版本兼容性（PowerShell 5.1 与 7+）、配置文件性能优化、高级函数参数验证，以及将分散脚本重构为标准化模块。适用于自动化运维、DevOps、IT基础设施管理及企业脚本库建设。关键词：PowerShell 模块设计，脚本重构，跨版本兼容，配置文件优化，自动化运维，企业级脚本库。

DevOps 0 次安装 0 次浏览 更新于 2/23/2026

名称: powershell-模块架构师 描述: 当用户需要PowerShell模块设计、函数结构、可重用库、配置文件优化或跨PowerShell 5.1和PowerShell 7+版本兼容性时使用。

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个以上相关函数 创建模块
需要跨团队共享 创建模块 + 清单
单次使用的自动化 保留为脚本
复杂的参数集 模块中的高级函数
需要版本兼容性 带有兼容性层的模块

模块结构决策

脚本组织需求
│
├─ 少量相关函数 (3-10)?
│  └─ 单个 .psm1 文件，内联函数
│
├─ 大量函数 (10+)?
│  └─ 点源模式（公共/私有文件夹）
│
├─ 发布到库？
│  └─ 完整清单 + 测试 + 文档
│
└─ 团队协作？
   └─ Git仓库 + CI/CD + Pester测试

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

使用案例： 将10-50个分散的.ps1脚本重构为有组织的模块

步骤1：分析

# 清点现有脚本
$scripts = Get-ChildItem -Path ./scripts -Filter *.ps1 -Recurse

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

# 预期输出：
# AD-UserManagement.ps1: 12 个函数
# AD-GroupManagement.ps1: 8 个函数
# Common-Helpers.ps1: 15 个函数（私有文件夹候选）

步骤2：设计模块结构

# 创建模块骨架
$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：分类函数

公共函数（导出给用户）：
  ├─ Get-OrgADUser
  ├─ New-OrgADUser
  ├─ Set-OrgADUser
  ├─ Remove-OrgADUser
  └─ ...（面向用户的函数）

私有函数（内部辅助函数）：
  ├─ _ValidateDomainConnection
  ├─ _BuildDistinguishedName
  ├─ _ConvertToCanonicalName
  └─ ...（实用函数）

步骤4：实现模块文件

# Organization.ActiveDirectory.psm1

# 首先点源私有函数
$Private = @(Get-ChildItem -Path $PSScriptRoot\Private\*.ps1 -ErrorAction SilentlyContinue)
foreach ($import in $Private) {
    try {
        . $import.FullName
    } catch {
        Write-Error "导入私有函数 $($import.FullName) 失败：$_"
    }
}

# 点源公共函数
$Public = @(Get-ChildItem -Path $PSScriptRoot\Public\*.ps1 -ErrorAction SilentlyContinue)
foreach ($import in $Public) {
    try {
        . $import.FullName
    } catch {
        Write-Error "导入公共函数 $($import.FullName) 失败：$_"
    }
}

# 显式导出公共函数
Export-ModuleMember -Function $Public.BaseName

步骤5：创建模块清单

# 生成清单
$manifestParams = @{
    Path              = "$modulePath/$moduleName.psd1"
    RootModule        = "$moduleName.psm1"
    ModuleVersion     = '1.0.0'
    Author            = 'IT团队'
    CompanyName       = '组织'
    Description       = 'Active Directory 管理函数'
    PowerShellVersion = '5.1'  # 最低版本
    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 模块" {
    It "导出预期的函数" {
        $commands = Get-Command -Module Organization.ActiveDirectory
        $commands.Count | Should -BeGreaterThan 0
    }
    
    It "具有有效的模块清单" {
        $manifest = Test-ModuleManifest -Path "$PSScriptRoot/../Organization.ActiveDirectory.psd1"
        $manifest.Version | Should -Be '1.0.0'
    }
}

Describe "Get-OrgADUser" {
    It "接受 Identity 参数" {
        { Get-OrgADUser -Identity "testuser" -WhatIf } | Should -Not -Throw
    }
}

快速参考：高级函数模板

function Get-OrgUser {
    <#
    .SYNOPSIS
        按名称检索Active Directory用户。
    
    .DESCRIPTION
        查询Active Directory用户对象并返回详细属性。
    
    .PARAMETER Name
        要搜索的用户名或SamAccountName。
    
    .EXAMPLE
        Get-OrgUser -Name "jdoe"
        
        返回用户jdoe的所有属性。
    
    .EXAMPLE
        "jdoe", "asmith" | Get-OrgUser
        
        通过管道检索多个用户。
    #>
    [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

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