使用 awesome-copilot 的 dataverse-python-production-code 技能生成生产级 Dataverse Python 代码【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot导读dataverse-python-production-code是 awesome-copilot 仓库中面向 GitHub Copilot 的 Agent Skill定义于 skills/dataverse-python-production-code/SKILL.md它把微软 PowerPlatform-Dataverse-Client SDK 的工程化最佳实践固化为一套可复用的系统指令当你在 GitHub Copilot 中要求生成 Dataverse 相关 Python 代码时它会自动产出具备错误处理、指数退避重试、单例客户端、OData 优化、结构化日志与完整类型注解的生产级代码。读完本文你将掌握该技能的全部规则、其底层依据对应 instructions 系列文档并能在自己的项目里直接复制这套代码骨架运行。技能定位把能跑的代码升级为能上生产的代码该 Skill 的 frontmatter 明确声明了它的使命生成使用 Dataverse SDK 的生产就绪production-readyPython 代码并强制要求使用DataverseError异常层级实现正确的错误处理用单例客户端模式管理连接为 429 / 超时错误实现指数退避重试应用 OData 优化服务端过滤、只 select 需要的列实现用于审计与调试的日志包含类型注解type hints与 docstring遵循微软官方示例的最佳实践。它本质上是一份生成规范告诉 Copilot生成的代码必须长什么样而不是一份 SDK 使用手册。因此下面各节把它的每一条生成规则与仓库内对应的 instructions 文档逐一对照让你既知道规则是什么也知道为什么这样定。错误处理结构以 DataverseError 异常层级为核心SKILL.md 给出的基础错误处理骨架如下from PowerPlatform.Dataverse.core.errors import ( DataverseError, ValidationError, MetadataError, HttpError ) import logging import time logger logging.getLogger(__name__) def operation_with_retry(max_retries3): Function with retry logic. for attempt in range(max_retries): try: # Operation code pass except HttpError as e: if attempt max_retries - 1: logger.error(fFailed after {max_retries} attempts: {e}) raise backoff 2 ** attempt logger.warning(fAttempt {attempt 1} failed. Retrying in {backoff}s) time.sleep(backoff)要真正正确地使用这个层级需要理解异常类携带的诊断信息。dataverse-python-error-handling.instructions.md 给出了DataverseError的完整构造与属性属性类型含义messagestr人类可读的错误消息codestr错误类别如validation_error、http_errorsubcodestr \| None更具体的错误标识符status_codeint \| NoneHTTP 状态码401、403、429 等detailsDict[str, Any] \| None附加诊断信息sourcestr \| None错误来源client或serveris_transientbool是否可能通过重试成功to_dict()dict转为字典便于日志记录典型的使用模式是按status_code分派处理try: client.get(account, record_idinvalid-id) except DataverseError as e: if e.status_code 401: # 认证失败检查凭据与令牌过期不要重试 print(Re-authenticate required) elif e.status_code 404: # 资源不存在使用默认数据兜底 record {name: Unknown, id: None} elif e.is_transient: # 瞬时错误可以重试 print(Transient error - may retry) else: raise重试策略哪些错误该重试哪些不该该技能要求为 429/超时错误实现指数退避重试文档中给出了明确的边界不要重试401认证失败、403授权失败、400客户端请求错误、404资源不存在。应该重试408、429、500、502、503、504并结合is_transient判断def should_retry(error: DataverseError) - bool: Determine if operation should be retried. if not error.is_transient: return False retryable_codes {408, 429, 500, 502, 503, 504} return error.status_code in retryable_codes def call_with_exponential_backoff(func, *args, max_attempts3, **kwargs): Call function with exponential backoff retry. for attempt in range(max_attempts): try: return func(*args, **kwargs) except DataverseError as e: if should_retry(e) and attempt max_attempts - 1: wait_time 2 ** attempt # 1s, 2s, 4s... print(fAttempt {attempt 1} failed. Retrying in {wait_time}s...) time.sleep(wait_time) else: raise注意一个关键前提dataverse-python-performance-optimization.instructions.md 明确指出该 SDK 的内置重试策略极简默认仅重试网络错误429 限流需要开发者手动处理这正是技能强制生成自定义重试逻辑的原因。客户端管理模式单例复用连接SKILL.md 提供的单例模板是生产代码的核心class DataverseService: _instance None _client None def __new__(cls, *args, **kwargs): if cls._instance is None: cls._instance super().__new__(cls) return cls._instance def __init__(self, org_url, credential): if self._client is None: self._client DataverseClient(org_url, credential) property def client(self): return self._client创建DataverseClient涉及认证握手与连接建立成本较高。反复 new 客户端是明确的反模式# ❌ ANTI-PATTERN: 每次调用都创建新客户端 def fetch_account(account_id): credential InteractiveBrowserCredential() client DataverseClient(https://yourorg.crm.dynamics.com, credential) return client.get(account, account_id) # ✅ 正确做法全局单例创建一次反复复用 from azure.identity import DefaultAzureCredential from PowerPlatform.Dataverse.client import DataverseClient _client None def get_client(): global _client if _client is None: _client DataverseClient( base_urlhttps://myorg.crm.dynamics.com, credentialDefaultAzureCredential() ) return _client认证方式与环境匹配SKILL 要求配置管理secrets、URLs落到代码里。Dataverse SDK 基于 Azure Identity 做令牌认证不同运行环境应选择不同凭据类型详见 dataverse-python-authentication-security.instructions.md本地开发InteractiveBrowserCredential()弹浏览器交互登录多环境应用推荐生产DefaultAzureCredential()按环境变量 → VS Code → Azure CLI → PowerShell → 托管标识链式探测同一份代码可在 dev/test/prod 无改动运行无值守任务定时作业、脚本、本地服务ClientSecretCredential从AZURE_TENANT_ID、AZURE_CLIENT_ID、AZURE_CLIENT_SECRET环境变量读取服务主体 客户端密钥高安全环境ClientCertificateCredential证书认证。安全要点严禁把密钥硬编码进源码一律通过环境变量或 Azure Key Vault 注入。客户端配置from PowerPlatform.Dataverse.core.config import DataverseConfig cfg DataverseConfig(language_code1033) # 默认 1033英文 cfg.http_timeout 30 # 请求超时 cfg.connection_timeout 5 # 连接超时 client DataverseClient( base_urlhttps://myorg.crm.dynamics.com, credentialcredential, configcfg )其中language_code控制 API 返回的语言默认 1033http_retries/http_backoff/http_timeout在配置类中为内部保留项。日志模式用 logger 取代 print为审计与排障留痕SKILL.md 给出了标准日志初始化模板import logging logging.basicConfig( levellogging.INFO, format%(asctime)s - %(name)s - %(levelname)s - %(message)s ) logger logging.getLogger(__name__) logger.info(fCreated {count} records) logger.warning(fRecord {id} not found) logger.error(fOperation failed: {error})生产级场景下dataverse-python-error-handling.instructions.md 还建议同时输出到文件与标准输出并单独开启 SDK 内部日志import logging import sys logging.basicConfig( levellogging.DEBUG, format%(asctime)s - %(name)s - %(levelname)s - %(message)s, handlers[ logging.FileHandler(dataverse_sdk.log), logging.StreamHandler(sys.stdout) ] ) logging.getLogger(azure).setLevel(logging.DEBUG) logging.getLogger(PowerPlatform).setLevel(logging.DEBUG)对于审计场景建议把错误序列化为结构化 JSON 记录含时间戳、上下文、error.to_dict()并用装饰器包装操作以记录每次调用的耗时与成败这样既有审计留痕又能发现性能劣化。OData 优化把计算留在服务端SKILL.md 的 OData 优化规则非常精炼核心四条始终带select参数限制返回列在服务端用filter过滤使用小写逻辑名用orderby、top做分页可用时用expand拉取关联记录。对应到代码dataverse-python-best-practices.instructions.md 与 dataverse-python-performance-optimization.instructions.md# ❌ 慢取全列再在内存里过滤 accounts client.get(account, top100) active [a for a in accounts if a.get(statecode) 0] # ✅ 快服务端过滤 只取需要的列 accounts client.get( account, select[accountid, name, telephone1, creditlimit], filterstatecode eq 0, top100 )大小写规则是最容易踩的坑filter 中的逻辑名必须小写filtername eq Contoso正确Name eq Contoso会失败而字符串值本身仍区分大小写。常用 filter 表达式filterstatecode eq 0 # 相等 filtercontains(name, Acme) # 包含 filtercreditlimit gt 50000 # 大于 filtercreatedon lt 2024-01-01 # 小于 filter(name eq Contoso) and (creditlimit gt 50000) # 与 filter(industrycode eq 1) or (industrycode eq 2) # 或 filternot(statecode eq 1) # 非分页与批量操作client.get返回懒加载的生成器逐页拉取内存友好pages client.get( account, select[accountid, name, createdon], orderby[name asc], top5000, # 总上限 page_size500 # 每页大小 ) for page in pages: for record in page: process_record(record)批量写操作优先一次调用传多记录SDK 自动使用 CreateMultiple / 批量更新避免循环内逐个createpayloads [{name: fAccount {i}, telephone1: f555-{i:04d}} for i in range(1000)] ids client.create(account, payloads) # 一次 API 调用创建多条批量大小可按表复杂度调整OOB 表Account/Contact/Lead200–300 条/批、简单表 ≤10、中等复杂 ≤100、大型复杂表 10–20 条/批。超大文件128 MB上传时使用client.upload_file(..., modechunk, if_none_matchTrue)SDK 自动按 4 MB 分片并行上传。代码结构规范与质量检查清单SKILL.md 规定生成的代码必须遵循固定结构Imports标准库 → 第三方 → 本地模块常量与枚举日志配置辅助函数核心服务类错误处理类使用示例。同时设置了一份可当评审标准用的质量清单全部代码必须是语法正确的Python 3.10API 调用必须包含 try-except函数参数与返回值必须有类型注解所有函数必须有 docstring瞬时故障必须实现重试逻辑消息输出必须用logger而非print()必须包含配置管理secrets、URLs 从环境注入遵循 PEP 8注释中必须给出使用示例。当用户请求生成代码时技能要求 Copilot 按固定顺序交付Imports 段 → 配置段常量/枚举→ 主体实现含错误处理→ docstring → 类型注解 → 使用示例 → 错误场景 → 日志语句确保每次生成的结构一致、可评审、可维护。实战把规则拼成一份完整的生产级服务把以上模式组合起来即得到技能期望的最终形态——一个可复制的生产级服务结合 dataverse-python-sdk.instructions.md 的 CRUD 语义create返回 GUID 列表、update/delete返回 NoneDataverse 生产级服务单例 重试 日志 OData 优化。 import logging import os import time from typing import Any, Dict, List from azure.identity import DefaultAzureCredential from PowerPlatform.Dataverse.client import DataverseClient from PowerPlatform.Dataverse.core.config import DataverseConfig from PowerPlatform.Dataverse.core.errors import DataverseError, HttpError logger logging.getLogger(__name__) logging.basicConfig(levellogging.INFO, format%(asctime)s - %(name)s - %(levelname)s - %(message)s) ORG_URL os.environ[DATAVERSE_ORG_URL] # 配置管理从环境注入 class DataverseService: 基于单例模式的 Dataverse 客户端封装。 _instance: DataverseService | None None _client: DataverseClient | None None def __new__(cls, *args, **kwargs) - DataverseService: if cls._instance is None: cls._instance super().__new__(cls) return cls._instance def __init__(self) - None: if self._client is None: cfg DataverseConfig(language_code1033) self._client DataverseClient( base_urlORG_URL, credentialDefaultAzureCredential(), configcfg, ) property def client(self) - DataverseClient: assert self._client is not None return self._client def create_with_retry(self, table: str, payload: Dict[str, Any], max_retries: int 3) - List[str]: 带指数退避重试的创建操作仅重试 429/5xx 等瞬时错误。 for attempt in range(max_retries): try: return self.client.create(table, payload) except HttpError as e: if attempt max_retries - 1 or e.status_code not in {408, 429, 500, 502, 503, 504}: raise wait 2 ** attempt logger.warning(Attempt %d failed with %s, retrying in %ss, attempt 1, e.status_code, wait) time.sleep(wait) raise RuntimeError(unreachable) def get_active_accounts(self, top: int 100) - List[Dict[str, Any]]: 服务端过滤 仅取所需列的分页查询。 records: List[Dict[str, Any]] [] for page in self.client.get( account, select[accountid, name, telephone1, creditlimit], filterstatecode eq 0, orderby[name asc], toptop, page_size200, ): records.extend(page) logger.info(Fetched %d active accounts, len(records)) return records与仓库其他资源的衔接该技能不是孤立的仓库为其准备了完整的学习与执行支撑链快速入门与 CRUD 语义dataverse-python-sdk.instructions.md安装pip install PowerPlatform-Dataverse-Client、连接、单条/批量 CRUD、表元数据操作错误处理与排障对照表dataverse-python-error-handling.instructions.md401/403/404/429/5xx 的成因与处置清单性能与优化dataverse-python-performance-optimization.instructions.mdselect/filter/分页/批量/限流/大文件分片最佳实践与反模式dataverse-python-best-practices.instructions.md单例、批量、PEP 8、Dos Donts认证与安全dataverse-python-authentication-security.instructions.md凭据选型与密钥管理。若在 Copilot 会话中加载该 Skill即可把上述全部规则固化为每次代码生成的默认行为。需要进一步定制生成风格时可参照仓库 instructions/instructions.instructions.md 的规范编写自定义指令文件并与该 Skill 组合使用。小结dataverse-python-production-code用一套可复现的代码骨架把 Dataverse SDK 生产化最关键的五个工程问题——错误分层与重试、连接复用、日志审计、OData 优化、代码结构一致性——固化为 Copilot 的生成契约。理解其每条规则的底层依据SDK 内建重试极简、批量操作自动优化、filter 需小写逻辑名、懒加载分页等你就能在 Copilot 之外手动复现同样的生产级代码并依据其质量清单完成代码评审。结合仓库内 instructions 系列文档与 SKILL.md 本身你可以持续迭代出符合团队规范的 Dataverse 数据访问层。【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考