\u9ed8\u8ba4\u503c\u7ba1\u7406\u5b8c\u6574\u6307\u5357 \u00b7 Default Values Management Guide<\/title>\n<style>\n*,*::before,*::after{box-sizing:border-box;margin:0;padding:0}\nhtml{scroll-behavior:smooth}\n:root{\n --bg:#f8f9fa;--bg2:#fff;--ink:#1a1a2e;--muted:#6c7086;--rule:#e2e4eb;\n --accent:#2563eb;--accent2:#16a34a;--accent3:#dc2626;--accent4:#d97706;--accent5:#7c3aed;\n --card-bg:#fff;--code-bg:#f1f3f5;\n --tag-g:#dcfce7;--tag-g-t:#166534;--tag-b:#dbeafe;--tag-b-t:#1e40af;\n --tag-r:#fee2e2;--tag-r-t:#991b1b;--tag-y:#fef9c3;--tag-y-t:#713f12;--tag-p:#f3e8ff;--tag-p-t:#581c87;\n --shadow:0 1px 3px rgba(0,0,.08);--radius:8px;--max-w:940px\n}\n[data-theme=\"dark\"]{\n --bg:#0b0b1a;--bg2:#16162a;--ink:#e2e4f0;--muted:#7f8396;--rule:#26263e;\n --accent:#60a5fa;--accent2:#4ade80;--accent3:#f87171;--accent4:#fbbf24;--accent5:#a78bfa;\n --card-bg:#16162a;--code-bg:#1e1e36;\n --tag-g:#14532d;--tag-g-t:#bbf7d0;--tag-b:#1e3a5f;--tag-b-t:#bfdbfe;\n --tag-r:#7f1d1d;--tag-r-t:#fecaca;--tag-y:#713f12;--tag-y-t:#fef08a;\n --tag-p:#3b1f6e;--tag-p-t:#e9d5ff;\n --shadow:0 1px 3px rgba(0,0,.3)\n}\nbody{font-family:-apple-system,BlinkMacSystemFont,\"Segoe UI\",\"Noto Sans SC\",\"PingFang SC\",\"Microsoft YaHei\",sans-serif;background:var(--bg);color:var(--ink);line-height:1.7;font-size:15px;transition:background .3s,color .3s}\nheader{position:fixed;top:0;left:0;right:0;z-index:100;background:var(--bg2);border-bottom:1px solid var(--rule);backdrop-filter:blur(12px);-webkit-backdrop-filter:blur(12px);transition:background .3s}\n.header-inner{max-width:var(--max-w);margin:0 auto;display:flex;align-items:center;justify-content:space-between;padding:0 1.5rem;height:56px}\n.logo{font-weight:700;font-size:.95rem;color:var(--accent);display:flex;align-items:center;gap:.4rem}\n.controls{display:flex;align-items:center;gap:.5rem}\n.lang-switch{display:flex;border:1px solid var(--rule);border-radius:6px;overflow:hidden}\n.lang-switch button{background:0 0;border:none;color:var(--muted);padding:.3rem .7rem;font-size:.8rem;cursor:pointer;transition:all .2s;font-family:inherit}\n.lang-switch button.active{background:var(--accent);color:#fff}\n.lang-switch button:not(.active):hover{color:var(--ink);background:var(--rule)}\n.theme-toggle{background:0 0;border:1px solid var(--rule);border-radius:6px;color:var(--muted);width:34px;height:34px;font-size:1rem;cursor:pointer;display:flex;align-items:center;transition:all .2s}\n.theme-toggle:hover{color:var(--ink);background:var(--rule)}\nmain{max-width:var(--max-w);margin:0 auto;padding:80px 1.5rem 3rem}\n.lang-section{display:none}.lang-section.active{display:block}\nh1{font-size:1.9rem;font-weight:800;line-height:1.3;margin-bottom:.5rem;letter-spacing:-.02em}\nh1 .sub{display:block;font-size:.85rem;font-weight:400;color:var(--muted);margin-top:.25rem;letter-spacing:0}\nh2{font-size:1.35rem;font-weight:700;margin:2.5rem 0 1rem;padding-bottom:.5rem;border-bottom:2px solid var(--accent);letter-spacing:-.01em}\nh3{font-size:1.05rem;font-weight:600;margin:1.5rem 0 .6rem;color:var(--accent)}\nh4{font-size:.95rem;font-weight:600;margin:1rem 0 .4rem;color:var(--ink)}\np{margin-bottom:.8rem}\na{color:var(--accent);text-decoration:none}a:hover{text-decoration:underline}\n.hero{text-align:center;padding:2rem 0 1rem}\n.hero p{font-size:1rem;color:var(--muted);max-width:700px;margin:0 auto}\n.tag{display:inline-block;padding:.12rem .5rem;border-radius:4px;font-size:.72rem;font-weight:600;margin-right:.25rem;white-space:nowrap}\n.tag-g{background:var(--tag-g);color:var(--tag-g-t)}.tag-b{background:var(--tag-b);color:var(--tag-b-t)}\n.tag-r{background:var(--tag-r);color:var(--tag-r-t)}.tag-y{background:var(--tag-y);color:var(--tag-y-t)}.tag-p{background:var(--tag-p);color:var(--tag-p-t)}\n.card{background:var(--card-bg);border:1px solid var(--rule);border-radius:var(--radius);padding:1.25rem;margin-bottom:1rem;box-shadow:var(--shadow)}\n.info-box{background:var(--bg);border-left:4px solid var(--accent);padding:.9rem 1.1rem;margin:1rem 0;border-radius:0 var(--radius) var(--radius) 0;font-size:.88rem}\n.info-box strong{color:var(--accent)}\n.info-box.warn{border-left-color:var(--accent4)}.info-box.warn strong{color:var(--accent4)}\n.info-box.danger{border-left-color:var(--accent3)}.info-box.danger strong{color:var(--accent3)}\n.toc{background:var(--card-bg);border:1px solid var(--rule);border-radius:var(--radius);padding:1.15rem 1.4rem;margin-bottom:2rem;box-shadow:var(--shadow)}\n.toc h3{margin:0 0 .5rem;font-size:.9rem;color:var(--muted);text-transform:uppercase;letter-spacing:.05em}\n.toc ol{padding-left:1.1rem;columns:2;column-gap:2rem}\n.toc li{margin-bottom:.25rem;font-size:.88rem}.toc a{color:var(--ink)}.toc a:hover{color:var(--accent);text-decoration:none}\npre.code-block{background:var(--code-bg);padding:.85rem 1rem;border-radius:var(--radius);overflow-x:auto;font-family:\"SF Mono\",Consolas,\"Courier New\",monospace;font-size:.82rem;line-height:1.5;margin:.6rem 0;border:1px solid var(--rule)}\ncode,.inline-code{background:var(--code-bg);padding:.12rem .4rem;border-radius:4px;font-family:\"SF Mono\",Consolas,\"Courier New\",monospace;font-size:.83rem;border:1px solid var(--rule)}\n.table-wrap{overflow-x:auto;margin:1.2rem 0}\ntable{width:100%;border-collapse:collapse;font-size:.82rem}\nthead th{background:var(--accent);color:#fff;padding:.6rem .5rem;text-align:center;font-weight:600;white-space:nowrap}\nthead th:first-child{border-radius:6px 0 0 0}thead th:last-child{border-radius:0 6px 0 0}\ntbody td{padding:.55rem .5rem;border-bottom:1px solid var(--rule);text-align:center;vertical-align:middle}\ntbody tr:nth-child(even){background:var(--bg)}\ntbody td:first-child{text-align:left;font-weight:600}\n.terminal{background:#1a1a2e;color:#a8e6cf;border-radius:var(--radius);padding:.9rem 1rem;font-family:\"SF Mono\",Consolas,\"Courier New\",monospace;font-size:.82rem;line-height:1.6;margin:.6rem 0;overflow-x:auto;border:1px solid #333}\n.terminal .prompt{color:#60a5fa}.terminal .comment{color:#6c7086;font-style:italic}.terminal .output{color:#e2e4f0}\n[data-theme=\"dark\"] .terminal{background:#08081a}\n.steps{counter-reset:step;list-style:none;padding:0}\n.steps li{counter-increment:step;position:relative;padding:.85rem 1rem .85rem 2.8rem;margin-bottom:.5rem;border-left:2px solid var(--rule);border-radius:0 var(--radius) 0;background:var(--card-bg);box-shadow:var(--shadow)}\n.steps li::before{content:counter(step);position:absolute;left:-13px;top:.85rem;width:26px;height:26px;border-radius:50%;background:var(--accent);color:#fff;display:flex;align-items:center;justify-content:center;font-size:.78rem;font-weight:700}\n.steps li .cmd{display:block;background:var(--code-bg);padding:.4rem .7rem;border-radius:5px;font-family:\"SF Mono\",Consolas,\"Courier New\",monospace;font-size:.82rem;margin:.3rem 0;overflow-x:auto;border:1px solid var(--rule)}\n.steps li .note{display:block;color:var(--muted);font-size:.82rem;margin-top:.2rem}\n.flow-diagram{background:var(--card-bg);border:1px solid var(--rule);border-radius:var(--radius);padding:1.25rem;margin:1.25rem 0;text-align:center}\n.flow-row{display:flex;align-items:center;justify-content:center;flex-wrap:wrap;gap:.35rem;margin:.4rem 0}\n.flow-item{display:inline-block;padding:.4rem .8rem;border-radius:6px;font-weight:600;font-size:.82rem;text-align:center;background:var(--accent);color:#fff;min-width:60px}\n.flow-item.green{background:var(--accent2)}.flow-item.red{background:var(--accent3)}.flow-item.yellow{background:var(--accent4);color:#1a1a2e}.flow-item.purple{background:var(--accent5)}\n.flow-arrow{color:var(--muted);font-size:1rem}\n.cmd-grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(280px,1fr));gap:.75rem;margin:1rem 0}\n.cmd-card{background:var(--card-bg);border:1px solid var(--rule);border-radius:var(--radius);padding:.9rem;box-shadow:var(--shadow)}\n.cmd-card h4{margin:0 0 .35rem;font-size:.88rem;color:var(--accent)}\n.cmd-card .cmd{font-family:\"SF Mono\",Consolas,\"Courier New\",monospace;font-size:.8rem;background:var(--code-bg);padding:.3rem .5rem;border-radius:4px;display:block;margin-bottom:.3rem;border:1px solid var(--rule)}\n.cmd-card .desc{font-size:.8rem;color:var(--muted)}\n.two-col{display:grid;grid-template-columns:1fr 1fr;gap:1.25rem;margin:1.25rem 0}\n.col{background:var(--card-bg);border:1px solid var(--rule);border-radius:var(--radius);padding:1.25rem;box-shadow:var(--shadow)}\n.col h4{margin-top:0}\n.compare-box{display:grid;grid-template-columns:1fr 1fr;gap:1rem;margin:1rem 0}\n.compare-col{background:var(--card-bg);border:1px solid var(--rule);border-radius:var(--radius);padding:1rem;box-shadow:var(--shadow)}\n.compare-col h4{margin:0 0 .4rem;font-size:.88rem}\n.compare-col.bad h4{color:var(--accent3)}\n.compare-col.good h4{color:var(--accent2)}\npre.example{background:var(--code-bg);padding:.6rem .8rem;border-radius:6px;font-family:\"SF Mono\",Consolas,\"Courier New\",monospace;font-size:.78rem;line-height:1.5;margin:.4rem 0;border:1px solid var(--rule);color:var(--ink)}\nfooter{max-width:var(--max-w);margin:3rem auto 0;padding:2rem 1.5rem 3rem;border-top:1px solid var(--rule);text-align:center;font-size:.82rem;color:var(--muted)}\nfooter .links{display:flex;justify-content:center;gap:1.5rem;flex-wrap:wrap;margin-bottom:.8rem}\nfooter .links a{color:var(--muted)}footer .links a:hover{color:var(--accent)}\n@media(max-width:640px){\n h1{font-size:1.4rem}.toc ol{columns:1}.header-inner{padding:0 1rem}main{padding:72px 1rem 2rem}\n .steps li{padding-left:2.4rem}.steps li::before{left:-11px;width:22px;height:22px;font-size:.7rem}\n .two-col{grid-template-columns:1fr}.cmd-grid{grid-template-columns:1fr}.compare-box{grid-template-columns:1fr}\n}\n<\/style>\n<\/head>\n<body>\n<header>\n <div class=\"header-inner\">\n <div class=\"logo\"><span>\u2699\ufe0f<\/span> \u9ed8\u8ba4\u503c\u7ba1\u7406\u5b8c\u6574\u6307\u5357<\/div>\n <div class=\"controls\">\n <div class=\"lang-switch\">\n <button class=\"active\" onclick=\"setLang('zh')\" id=\"btn-zh\">\u4e2d\u6587<\/button>\n <button onclick=\"setLang('en')\" id=\"btn-en\">English<\/button>\n <\/div>\n <button class=\"theme-toggle\" onclick=\"toggleTheme()\" title=\"\u5207\u6362\u660e\u6697\u4e3b\u9898\">☼<\/button>\n <\/div>\n <\/div>\n<\/header>\n<main>\n\n<div class=\"lang-section active\" id=\"lang-zh\">\n<div class=\"hero\">\n <h1>\u9ed8\u8ba4\u503c\u7ba1\u7406\u5b8c\u6574\u6307\u5357\uff08\u4e3a\u4f55\u9700\u8981\u2192\u5982\u4f55\u7edf\u4e00\u2192\u6700\u4f73\u5b9e\u8df5\uff09<span class=\"sub\">\u4ece\u7406\u89e3\u9ed8\u8ba4\u503c\u7684\u4ef7\u503c\u5230\u5efa\u7acb\u7edf\u4e00\u7684\u9ed8\u8ba4\u503c\u7ba1\u7406\u4f53\u7cfb<\/span><\/h1>\n <p>\u4e3a\u4ec0\u4e48\u9700\u8981\u9ed8\u8ba4\u503c\u3001\u9ed8\u8ba4\u503c\u7684\u5e94\u7528\u573a\u666f\u3001\u7edf\u4e00\u7ba1\u7406\u7b56\u7565\u3001\u914d\u7f6e\u6587\u4ef6\u8bbe\u8ba1\u3001\u4ee3\u7801\u5b9e\u73b0\u6a21\u5f0f\u3001\u73af\u5883\u5dee\u5f02\u5904\u7406\u3001\u5e38\u89c1\u95ee\u9898\u4e0e\u6700\u4f73\u5b9e\u8df5\u5168\u8986\u76d6<\/p>\n<\/div>\n\n<div class=\"toc\">\n <h3>\u76ee\u5f55<\/h3>\n <ol>\n <li><a href=\"#zh-1\">\u4e00\u3001\u4e3a\u4ec0\u4e48\u5f00\u53d1\u8fc7\u7a0b\u4e2d\u9700\u8981\u9ed8\u8ba4\u503c<\/a><\/li>\n <li><a href=\"#zh-2\">\u4e8c\u3001\u9ed8\u8ba4\u503c\u7684\u5e94\u7528\u573a\u666f\u5206\u7c7b<\/a><\/li>\n <li><a href=\"#zh-3\">\u4e09\u3001\u9ed8\u8ba4\u503c\u7684\u5e38\u89c1\u9677\u9631<\/a><\/li>\n <li><a href=\"#zh-4\">\u56db\u3001\u7edf\u4e00\u7ba1\u7406\u9ed8\u8ba4\u503c\u7684\u6838\u5fc3\u7b56\u7565<\/a><\/li>\n <li><a href=\"#zh-5\">\u4e94\u3001Python \u4e2d\u9ed8\u8ba4\u503c\u7ba1\u7406\u7684\u5b9e\u73b0\u6a21\u5f0f<\/a><\/li>\n <li><a href=\"#zh-6\">\u516d\u3001\u914d\u7f6e\u6587\u4ef6\u4e0e\u9ed8\u8ba4\u503c\u5206\u5c42\u8bbe\u8ba1<\/a><\/li>\n <li><a href=\"#zh-7\">\u4e03\u3001\u4e0d\u540c\u73af\u5883\u7684\u9ed8\u8ba4\u503c\u8986\u76d6<\/a><\/li>\n <li><a href=\"#zh-8\">\u516b\u3001\u9ed8\u8ba4\u503c\u53d8\u66f4\u4e0e\u7248\u672c\u7ba1\u7406<\/a><\/li>\n <li><a href=\"#zh-9\">\u4e5d\u3001\u9ed8\u8ba4\u503c\u4f7f\u7528\u6700\u4f73\u5b9e\u8df5<\/a><\/li>\n <li><a href=\"#zh-10\">\u5341\u3001\u5e38\u89c1\u95ee\u9898\u4e0e\u6392\u67e5<\/a><\/li>\n <\/ol>\n<\/div>\n\n\n<h2 id=\"zh-1\">\u4e00\u3001\u4e3a\u4ec0\u4e48\u5f00\u53d1\u8fc7\u7a0b\u4e2d\u9700\u8981\u9ed8\u8ba4\u503c<\/h2>\n\n<p>\u9ed8\u8ba4\u503c\uff08Default Value\uff09\u662f\u6307\u5728\u7528\u6237\u672a\u663e\u5f0f\u63d0\u4f9b\u67d0\u4e2a\u914d\u7f6e\u6216\u53c2\u6570\u65f6\uff0c\u7cfb\u7edf\u81ea\u52a8\u91c7\u7528\u7684\u9884\u8bbe\u503c\u3002\u5b83\u662f\u8fde\u63a5”\u7075\u6d3b\u914d\u7f6e”\u4e0e”\u5f00\u7bb1\u5373\u7528”\u7684\u5173\u952e\u6865\u6881\u3002<\/p>\n\n<div class=\"compare-box\">\n <div class=\"compare-col bad\">\n <h4>\u274c \u65e0\u9ed8\u8ba4\u503c\uff08\u5f3a\u5236\u914d\u7f6e\uff09<\/h4>\n<pre class=\"example\"># \u7528\u6237\u5fc5\u987b\u63d0\u4f9b\u6240\u6709\u53c2\u6570\nconnect_to_database(host=?, port=?, user=?, password=?,\n timeout=?, pool_size=?, charset=?)\n# \u542f\u52a8\u62a5\u9519\uff1a\u7f3a\u5c11\u5fc5\u586b\u53c2\u6570\n# \u6bcf\u4e2a\u65b0\u6210\u5458\u9700\u8981\u9605\u8bfb\u5927\u91cf\u6587\u6863\n# \u914d\u7f6e\u9879\u81a8\u80c0\uff0c50% \u7684\u53c2\u6570\u5927\u5bb6\u90fd\u7528\u540c\u4e00\u4e2a\u503c<\/pre>\n <p>\u4f7f\u7528\u95e8\u69db\u9ad8\u3001\u914d\u7f6e\u5197\u4f59\u3001\u542f\u52a8\u5931\u8d25\u7387\u9ad8\u3001\u65b0\u4eba\u4e0a\u624b\u6162\u3002<\/p>\n <\/div>\n <div class=\"compare-col good\">\n <h4>\u2705 \u5408\u7406\u9ed8\u8ba4\u503c\uff08\u4f18\u96c5\u964d\u7ea7\uff09<\/h4>\n<pre class=\"example\"># \u53ea\u9700\u63d0\u4f9b\u771f\u6b63\u4e2a\u6027\u5316\u7684\u53c2\u6570\nconnect_to_database(\n host=\"prod-db.internal\",\n password=os.getenv(\"DB_PASSWORD\")\n)\n# timeout=30, pool_size=10, charset=utf8mb4 \u81ea\u52a8\u751f\u6548\n# 90% \u7684\u573a\u666f\u65e0\u9700\u989d\u5916\u914d\u7f6e<\/pre>\n <p>\u964d\u4f4e\u4f7f\u7528\u95e8\u69db\u3001\u51cf\u5c11\u914d\u7f6e\u91cf\u3001\u63d0\u9ad8\u7a33\u5b9a\u6027\u3001\u52a0\u901f\u5f00\u53d1\u3002<\/p>\n <\/div>\n<\/div>\n\n<div class=\"card\">\n <h4>\u9ed8\u8ba4\u503c\u7684\u4e94\u5927\u6838\u5fc3\u4ef7\u503c<\/h4>\n <p><span class=\"tag tag-b\">\u964d\u4f4e\u95e8\u69db<\/span> \u65b0\u7528\u6237\u65e0\u9700\u4e86\u89e3\u6240\u6709\u7ec6\u8282\u5373\u53ef\u8fd0\u884c\uff0c\u5b9e\u73b0”\u5f00\u7bb1\u5373\u7528”<\/p>\n <p><span class=\"tag tag-g\">\u9632\u5fa1\u7f16\u7a0b<\/span> \u9632\u6b62\u56e0\u914d\u7f6e\u7f3a\u5931\u5bfc\u81f4\u7684\u8fd0\u884c\u65f6\u5f02\u5e38\uff0c\u63d0\u5347\u7cfb\u7edf\u9c81\u68d2\u6027<\/p>\n <p><span class=\"tag tag-y\">\u7edf\u4e00\u6807\u51c6<\/span> \u56e2\u961f\u5171\u4eab\u4e00\u5957\u7ecf\u8fc7\u9a8c\u8bc1\u7684\u57fa\u51c6\u914d\u7f6e\uff0c\u907f\u514d\u5404\u81ea\u4e3a\u653f<\/p>\n <p><span class=\"tag tag-p\">\u5411\u540e\u517c\u5bb9<\/span> \u65b0\u589e\u914d\u7f6e\u9879\u65f6\uff0c\u8001\u7528\u6237\u65e0\u9700\u4fee\u6539\u5373\u53ef\u5e73\u6ed1\u5347\u7ea7<\/p>\n <p><span class=\"tag tag-r\">\u5b89\u5168\u515c\u5e95<\/span> \u5173\u952e\u5b89\u5168\u53c2\u6570\uff08\u8d85\u65f6\u3001\u91cd\u8bd5\u6b21\u6570\uff09\u8bbe\u6709\u4fdd\u5b88\u9ed8\u8ba4\u503c\uff0c\u9632\u6b62\u8bef\u914d\u7f6e\u5bfc\u81f4\u4e8b\u6545<\/p>\n<\/div>\n\n<div class=\"info-box\">\n <strong>\u6838\u5fc3\u539f\u5219\uff1a\u9ed8\u8ba4\u503c\u4e0d\u662f”\u968f\u4fbf\u586b\u4e00\u4e2a\u503c”\uff0c\u800c\u662f\u7ecf\u8fc7\u56e2\u961f\u8bc4\u4f30\u3001\u751f\u4ea7\u9a8c\u8bc1\u3001\u6587\u6863\u8bf4\u660e\u7684”\u63a8\u8350\u914d\u7f6e”\u3002\u597d\u7684\u9ed8\u8ba4\u503c\u8ba9 80% \u7684\u7528\u6237\u65e0\u9700\u8c03\u6574\u5373\u53ef\u4f7f\u7528\uff0c20% \u7684\u9ad8\u7ea7\u7528\u6237\u53ef\u4ee5\u901a\u8fc7\u663e\u5f0f\u914d\u7f6e\u8986\u76d6\u3002<\/strong>\n<\/div>\n\n\n<h2 id=\"zh-2\">\u4e8c\u3001\u9ed8\u8ba4\u503c\u7684\u5e94\u7528\u573a\u666f\u5206\u7c7b<\/h2>\n\n<h3>2.1 \u6309\u4f5c\u7528\u57df\u5206\u7c7b<\/h3>\n<div class=\"table-wrap\">\n<table>\n <thead>\n <tr><th>\u4f5c\u7528\u57df<\/th><th>\u793a\u4f8b<\/th><th>\u7ba1\u7406\u65b9\u5f0f<\/th><\/tr>\n <\/thead>\n <tbody>\n <tr><td>\u8bed\u8a00\u7ea7\u9ed8\u8ba4<\/td><td>\u51fd\u6570\u53c2\u6570\u9ed8\u8ba4\u503c <code>def fn(x=10)<\/code><\/td><td>\u4ee3\u7801\u4e2d\u786c\u7f16\u7801<\/td><\/tr>\n <tr><td>\u6a21\u5757\u7ea7\u9ed8\u8ba4<\/td><td>\u6570\u636e\u5e93\u8fde\u63a5\u6c60\u5927\u5c0f\u3001HTTP \u8d85\u65f6\u65f6\u95f4<\/td><td>\u6a21\u5757\u5e38\u91cf\/\u914d\u7f6e\u7c7b<\/td><\/tr>\n <tr><td>\u9879\u76ee\u7ea7\u9ed8\u8ba4<\/td><td>\u670d\u52a1\u7aef\u53e3\u53f7\u3001\u65e5\u5fd7\u7ea7\u522b\u3001\u7ebf\u7a0b\u6570<\/td><td>\u914d\u7f6e\u6587\u4ef6\/\u73af\u5883\u53d8\u91cf<\/td><\/tr>\n <tr><td>\u73af\u5883\u7ea7\u9ed8\u8ba4<\/td><td>\u751f\u4ea7\/\u5f00\u53d1\u73af\u5883\u7684\u6570\u636e\u5e93\u5730\u5740<\/td><td>\u73af\u5883\u53d8\u91cf\/\u914d\u7f6e\u6587\u4ef6\u5206\u5c42<\/td><\/tr>\n <tr><td>\u7528\u6237\u7ea7\u9ed8\u8ba4<\/td><td>\u7528\u6237\u504f\u597d\u8bbe\u7f6e\u3001\u754c\u9762\u4e3b\u9898<\/td><td>\u7528\u6237\u914d\u7f6e\u6587\u4ef6\/\u6570\u636e\u5e93<\/td><\/tr>\n <\/tbody>\n<\/table>\n<\/div>\n\n<h3>2.2 \u6309\u7c7b\u578b\u5206\u7c7b<\/h3>\n<pre class=\"code-block\"># 1. \u51fd\u6570\/\u65b9\u6cd5\u53c2\u6570\u9ed8\u8ba4\u503c\ndef fetch_data(url: str, timeout: int = 30, retries: int = 3) -> dict:\n \"\"\"\u83b7\u53d6\u8fdc\u7a0b\u6570\u636e\uff0c\u8d85\u65f6\u9ed8\u8ba4 30 \u79d2\uff0c\u91cd\u8bd5\u9ed8\u8ba4 3 \u6b21\u3002\"\"\"\n\n# 2. \u7c7b\u5c5e\u6027\u9ed8\u8ba4\u503c\nclass DatabaseConfig:\n host: str = \"localhost\"\n port: int = 3306\n pool_size: int = 10\n charset: str = \"utf8mb4\"\n\n# 3. \u914d\u7f6e\u9879\u9ed8\u8ba4\u503c\nDEFAULT_CONFIG = {\n \"server\": {\"host\": \"0.0.0.0\", \"port\": 8000},\n \"database\": {\"timeout\": 30, \"pool_size\": 10},\n \"cache\": {\"ttl\": 3600, \"max_size\": 1000},\n \"logging\": {\"level\": \"INFO\", \"format\": \"standard\"},\n}\n\n# 4. \u73af\u5883\u53d8\u91cf\u9ed8\u8ba4\u503c\nDB_HOST = os.getenv(\"DB_HOST\", \"localhost\")\nDB_PORT = int(os.getenv(\"DB_PORT\", \"3306\"))\nDEBUG = os.getenv(\"DEBUG\", \"false\").lower() == \"true\"\n\n# 5. Pydantic \u6a21\u578b\u9ed8\u8ba4\u503c\nfrom pydantic import BaseModel, Field\n\nclass AppConfig(BaseModel):\n port: int = Field(default=8000, ge=1, le=65535)\n workers: int = Field(default=4, ge=1)\n timeout: float = Field(default=30.0, gt=0)\n<\/pre>\n\n\n<h2 id=\"zh-3\">\u4e09\u3001\u9ed8\u8ba4\u503c\u7684\u5e38\u89c1\u9677\u9631<\/h2>\n\n<h3>3.1 Python \u53ef\u53d8\u9ed8\u8ba4\u53c2\u6570\u9677\u9631<\/h3>\n<div class=\"compare-box\">\n <div class=\"compare-col bad\">\n <h4>\u274c \u9519\u8bef\u7684\u53ef\u53d8\u9ed8\u8ba4\u503c<\/h4>\n<pre class=\"example\">def append_item(item, items=[]):\n items.append(item)\n return items\n\nprint(append_item(1)) # [1]\nprint(append_item(2)) # [1, 2] \u2190 \u610f\u5916\uff01<\/pre>\n <p>\u5217\u8868\u5728\u51fd\u6570\u5b9a\u4e49\u65f6\u521b\u5efa\uff0c\u88ab\u591a\u6b21\u8c03\u7528\u5171\u4eab\uff0c\u5bfc\u81f4\u72b6\u6001\u6cc4\u6f0f\u3002<\/p>\n <\/div>\n <div class=\"compare-col good\">\n <h4>\u2705 \u6b63\u786e\u7684\u505a\u6cd5<\/h4>\n<pre class=\"example\">def append_item(item, items=None):\n if items is None:\n items = []\n items.append(item)\n return items\n\nprint(append_item(1)) # [1]\nprint(append_item(2)) # [2] \u2190 \u6b63\u786e<\/pre>\n <p>\u4f7f\u7528 None \u4f5c\u4e3a\u54e8\u5175\u503c\uff0c\u5728\u51fd\u6570\u4f53\u5185\u521b\u5efa\u65b0\u5bf9\u8c61\u3002<\/p>\n <\/div>\n<\/div>\n\n<h3>3.2 \u5176\u4ed6\u5e38\u89c1\u9677\u9631<\/h3>\n<div class=\"table-wrap\">\n<table>\n <thead>\n <tr><th>\u9677\u9631<\/th><th>\u73b0\u8c61<\/th><th>\u89e3\u51b3\u65b9\u6848<\/th><\/tr>\n <\/thead>\n <tbody>\n <tr>\n <td>\u9b54\u6cd5\u6570\u5b57\u6563\u843d<\/td>\n <td>\u4ee3\u7801\u5404\u5904\u51fa\u73b0 30\u30013600\u30011024 \u7b49\u6570\u5b57\uff0c\u542b\u4e49\u4e0d\u660e<\/td>\n <td>\u63d0\u53d6\u4e3a\u547d\u540d\u5e38\u91cf\uff0c\u5982 TIMEOUT_SECONDS = 30<\/td>\n <\/tr>\n <tr>\n <td>\u9ed8\u8ba4\u503c\u8fc7\u4e8e\u6fc0\u8fdb<\/td>\n <td>\u9ed8\u8ba4\u8fde\u63a5\u6c60 100\uff0c\u672c\u5730\u5f00\u53d1\u76f4\u63a5\u8017\u5c3d\u6570\u636e\u5e93\u8d44\u6e90<\/td>\n <td>\u9ed8\u8ba4\u503c\u504f\u4fdd\u5b88\uff0c\u6309\u73af\u5883\u63d0\u4f9b\u8986\u76d6\u65b9\u6848<\/td>\n <\/tr>\n <tr>\n <td>\u9ed8\u8ba4\u503c\u4e0e\u5b9e\u9645\u8131\u8282<\/td>\n <td>\u6587\u6863\u5199\u9ed8\u8ba4 30 \u79d2\uff0c\u4ee3\u7801\u91cc\u662f 60 \u79d2<\/td>\n <td>\u5355\u4e00\u6570\u636e\u6e90\uff0c\u4ee3\u7801\u4e0e\u6587\u6863\u81ea\u52a8\u751f\u6210<\/td>\n <\/tr>\n <tr>\n <td>\u9ed8\u8ba4\u503c\u672a\u6587\u6863\u5316<\/td>\n <td>\u7528\u6237\u4e0d\u77e5\u9053\u67d0\u4e2a\u53c2\u6570\u7684\u9ed8\u8ba4\u503c\u662f\u4ec0\u4e48<\/td>\n <td>\u5728\u51fd\u6570\u7b7e\u540d\u3001\u914d\u7f6e\u6587\u4ef6\u6a21\u677f\u4e2d\u663e\u5f0f\u6807\u6ce8<\/td>\n <\/tr>\n <tr>\n <td>\u5e03\u5c14\u9ed8\u8ba4\u503c\u6b67\u4e49<\/td>\n <td><code>flag=True<\/code> \u8bed\u4e49\u4e0d\u6e05\uff0c\u4e0d\u77e5\u9053\u4ee3\u8868\u4ec0\u4e48<\/td>\n <td>\u4f7f\u7528\u5177\u540d\u53c2\u6570\u6216\u679a\u4e3e\uff0c\u5982 <code>mode=Mode.AUTO<\/code><\/td>\n <\/tr>\n <\/tbody>\n<\/table>\n<\/div>\n\n\n<h2 id=\"zh-4\">\u56db\u3001\u7edf\u4e00\u7ba1\u7406\u9ed8\u8ba4\u503c\u7684\u6838\u5fc3\u7b56\u7565<\/h2>\n\n<h3>4.1 \u5355\u4e00\u6570\u636e\u6e90\u539f\u5219\uff08Single Source of Truth\uff09<\/h3>\n<div class=\"flow-diagram\">\n <div class=\"flow-row\">\n <span class=\"flow-item green\">defaults.py<\/span>\n <span class=\"flow-arrow\">←<\/span>\n <span class=\"flow-item\">\u552f\u4e00\u9ed8\u8ba4\u503c\u5b9a\u4e49<\/span>\n <span class=\"flow-arrow\">→<\/span>\n <span class=\"flow-item yellow\">\u914d\u7f6e\u6587\u4ef6<\/span>\n <span class=\"flow-arrow\">→<\/span>\n <span class=\"flow-item purple\">\u73af\u5883\u53d8\u91cf<\/span>\n <span class=\"flow-arrow\">→<\/span>\n <span class=\"flow-item\">\u8fd0\u884c\u65f6\u8986\u76d6<\/span>\n <\/div>\n<\/div>\n\n<div class=\"info-box\">\n <strong>\u4f18\u5148\u7ea7\u89c4\u5219\uff1a\u8fd0\u884c\u65f6\u4f20\u5165 > \u73af\u5883\u53d8\u91cf > \u914d\u7f6e\u6587\u4ef6 > \u4ee3\u7801\u9ed8\u8ba4\u503c\u3002\u4efb\u4f55\u5c42\u7ea7\u7684\u914d\u7f6e\u90fd\u5e94\u5f53\u4ee5\u4ee3\u7801\u4e2d\u7684\u9ed8\u8ba4\u503c\u4e3a\u6700\u7ec8\u515c\u5e95\u3002<\/strong>\n<\/div>\n\n<h3>4.2 \u63a8\u8350\u7684\u5c42\u7ea7\u8986\u76d6\u67b6\u6784<\/h3>\n<pre class=\"code-block\">\u914d\u7f6e\u52a0\u8f7d\u4f18\u5148\u7ea7\uff08\u4ece\u9ad8\u5230\u4f4e\uff09\uff1a\n\n1. \u547d\u4ee4\u884c\u53c2\u6570\uff08\u6700\u4f18\u5148\uff0c\u4e34\u65f6\u8c03\u8bd5\uff09\n python main.py --port 9000 --debug\n\n2. \u73af\u5883\u53d8\u91cf\uff08CI\/CD \u90e8\u7f72\u65f6\u6ce8\u5165\uff09\n export APP_PORT=9000\n export APP_DEBUG=true\n\n3. \u672c\u5730\u914d\u7f6e\u6587\u4ef6\uff08\u5f00\u53d1\u73af\u5883\u4e2a\u6027\u5316\uff09\n config\/dev.yaml\n\n4. \u9879\u76ee\u9ed8\u8ba4\u914d\u7f6e\uff08\u4ed3\u5e93\u4e2d\u63d0\u4ea4\u7684\u57fa\u7840\u503c\uff09\n config\/default.yaml\n\n5. \u4ee3\u7801\u786c\u7f16\u7801\u9ed8\u8ba4\u503c\uff08\u6700\u7ec8\u515c\u5e95\uff09\n PORT: int = 8000\n<\/pre>\n\n\n<h2 id=\"zh-5\">\u4e94\u3001Python \u4e2d\u9ed8\u8ba4\u503c\u7ba1\u7406\u7684\u5b9e\u73b0\u6a21\u5f0f<\/h2>\n\n<h3>5.1 \u6a21\u5f0f\u4e00\uff1a\u5e38\u91cf\u6a21\u5757<\/h3>\n<pre class=\"code-block\"># src\/myapp\/defaults.py\n\"\"\"\u9879\u76ee\u6240\u6709\u9ed8\u8ba4\u503c\u7684\u5355\u4e00\u6570\u636e\u6e90\u3002\"\"\"\n\nfrom pathlib import Path\n\n# \u670d\u52a1\u5668\nDEFAULT_HOST: str = \"0.0.0.0\"\nDEFAULT_PORT: int = 8000\nDEFAULT_WORKERS: int = 4\nDEFAULT_TIMEOUT: float = 30.0\n\n# \u6570\u636e\u5e93\nDEFAULT_DB_HOST: str = \"localhost\"\nDEFAULT_DB_PORT: int = 3306\nDEFAULT_DB_POOL_SIZE: int = 10\nDEFAULT_DB_CHARSET: str = \"utf8mb4\"\n\n# \u7f13\u5b58\nDEFAULT_CACHE_TTL: int = 3600\nDEFAULT_CACHE_MAX_SIZE: int = 1000\n\n# \u65e5\u5fd7\nDEFAULT_LOG_LEVEL: str = \"INFO\"\nDEFAULT_LOG_FORMAT: str = \"standard\"\nDEFAULT_LOG_FILE: Path = Path(\"logs\/app.log\")\n\n# \u5176\u4ed6\nMAX_UPLOAD_SIZE: int = 10 * 1024 * 1024 # 10MB\nREQUEST_RETRY_COUNT: int = 3\nREQUEST_RETRY_BACKOFF: float = 1.5\n<\/pre>\n\n<h3>5.2 \u6a21\u5f0f\u4e8c\uff1aPydantic Settings\uff08\u63a8\u8350\uff09<\/h3>\n<pre class=\"code-block\"># src\/myapp\/config.py\nfrom pydantic import Field\nfrom pydantic_settings import BaseSettings, SettingsConfigDict\n\n\nclass DatabaseConfig(BaseSettings):\n \"\"\"\u6570\u636e\u5e93\u914d\u7f6e\uff0c\u652f\u6301\u73af\u5883\u53d8\u91cf\u8986\u76d6\u3002\"\"\"\n model_config = SettingsConfigDict(env_prefix=\"DB_\")\n\n host: str = Field(default=\"localhost\", description=\"\u6570\u636e\u5e93\u5730\u5740\")\n port: int = Field(default=3306, ge=1, le=65535)\n user: str = Field(default=\"root\")\n password: str = Field(default=\"\")\n pool_size: int = Field(default=10, ge=1, le=100)\n timeout: float = Field(default=30.0, gt=0)\n charset: str = Field(default=\"utf8mb4\")\n\n\nclass AppConfig(BaseSettings):\n \"\"\"\u5e94\u7528\u5168\u5c40\u914d\u7f6e\u3002\"\"\"\n model_config = SettingsConfigDict(\n env_file=\".env\",\n env_file_encoding=\"utf-8\",\n extra=\"ignore\"\n )\n\n env: str = Field(default=\"dev\", pattern=\"^(dev|test|staging|prod)$\")\n host: str = Field(default=\"0.0.0.0\")\n port: int = Field(default=8000, ge=1, le=65535)\n workers: int = Field(default=4, ge=1)\n debug: bool = Field(default=False)\n\n database: DatabaseConfig = Field(default_factory=DatabaseConfig)\n\n log_level: str = Field(default=\"INFO\")\n log_format: str = Field(default=\"standard\")\n\n\n# \u4f7f\u7528\nconfig = AppConfig()\nprint(config.port) # 8000\uff08\u9ed8\u8ba4\u503c\uff09\nprint(config.database.host) # localhost\uff08\u9ed8\u8ba4\u503c\uff09\n# \u73af\u5883\u53d8\u91cf DB_HOST=prod-db \u65f6\uff0cconfig.database.host = \"prod-db\"\n<\/pre>\n\n<h3>5.3 \u6a21\u5f0f\u4e09\uff1adataclasses + \u5408\u5e76<\/h3>\n<pre class=\"code-block\">from dataclasses import dataclass, field, asdict\nfrom typing import Optional\nimport os\n\n\n@dataclass\nclass ServerConfig:\n host: str = \"0.0.0.0\"\n port: int = 8000\n workers: int = 4\n\n\n@dataclass\nclass AppConfig:\n env: str = \"dev\"\n debug: bool = False\n server: ServerConfig = field(default_factory=ServerConfig)\n\n @classmethod\n def from_env(cls) -> \"AppConfig\":\n \"\"\"\u4ece\u73af\u5883\u53d8\u91cf\u52a0\u8f7d\uff0c\u8986\u76d6\u9ed8\u8ba4\u503c\u3002\"\"\"\n cfg = cls()\n if \"APP_PORT\" in os.environ:\n cfg.server.port = int(os.environ[\"APP_PORT\"])\n if \"APP_DEBUG\" in os.environ:\n cfg.debug = os.environ[\"APP_DEBUG\"].lower() == \"true\"\n return cfg\n\n def merge(self, overrides: dict) -> \"AppConfig\":\n \"\"\"\u5408\u5e76\u5b57\u5178\u8986\u76d6\u5230\u5f53\u524d\u914d\u7f6e\u3002\"\"\"\n data = asdict(self)\n data.update(overrides)\n return self.__class__(**data)\n<\/pre>\n\n\n<h2 id=\"zh-6\">\u516d\u3001\u914d\u7f6e\u6587\u4ef6\u4e0e\u9ed8\u8ba4\u503c\u5206\u5c42\u8bbe\u8ba1<\/h2>\n\n<h3>6.1 \u63a8\u8350\u9879\u76ee\u7ed3\u6784<\/h3>\n<pre class=\"code-block\">config\/\n\u251c\u2500\u2500 default.yaml # \u6240\u6709\u9ed8\u8ba4\u503c\uff0c\u63d0\u4ea4\u5230 Git\n\u251c\u2500\u2500 default.yaml.example # \u5e26\u8bf4\u660e\u7684\u6a21\u677f\uff08\u65b0\u4eba\u53c2\u8003\uff09\n\u251c\u2500\u2500 dev.yaml # \u5f00\u53d1\u73af\u5883\u8986\u76d6\uff08\u53ef\u9009\uff0c\u4e0d\u63d0\u4ea4 Git\uff09\n\u251c\u2500\u2500 test.yaml # \u6d4b\u8bd5\u73af\u5883\u8986\u76d6\n\u2514\u2500\u2500 prod.yaml # \u751f\u4ea7\u73af\u5883\u8986\u76d6\uff08CI\/CD \u6ce8\u5165\uff09\n<\/pre>\n\n<h3>6.2 default.yaml \u8bbe\u8ba1<\/h3>\n<pre class=\"code-block\"># config\/default.yaml\n# \u6240\u6709\u914d\u7f6e\u9879\u5fc5\u987b\u6709\u9ed8\u8ba4\u503c\uff0c\u6ce8\u91ca\u8bf4\u660e\u7528\u9014\u548c\u5355\u4f4d\n\nserver:\n host: \"0.0.0.0\" # \u76d1\u542c\u5730\u5740\uff0c0.0.0.0 \u8868\u793a\u6240\u6709\u63a5\u53e3\n port: 8000 # \u670d\u52a1\u7aef\u53e3\n workers: 4 # \u5de5\u4f5c\u8fdb\u7a0b\u6570\uff0cCPU \u6838\u5fc3\u6570\u7684 2 \u500d\u4e3a\u5b9c\n timeout: 30.0 # \u8bf7\u6c42\u8d85\u65f6\u65f6\u95f4\uff08\u79d2\uff09\n\ndatabase:\n host: \"localhost\" # \u6570\u636e\u5e93\u5730\u5740\n port: 3306 # \u6570\u636e\u5e93\u7aef\u53e3\n pool_size: 10 # \u8fde\u63a5\u6c60\u5927\u5c0f\n timeout: 30.0 # \u8fde\u63a5\u8d85\u65f6\uff08\u79d2\uff09\n charset: \"utf8mb4\" # \u6570\u636e\u5e93\u5b57\u7b26\u96c6\n\ncache:\n enabled: true # \u662f\u5426\u542f\u7528\u7f13\u5b58\n ttl: 3600 # \u7f13\u5b58\u8fc7\u671f\u65f6\u95f4\uff08\u79d2\uff09\n max_size: 1000 # \u6700\u5927\u7f13\u5b58\u6761\u76ee\u6570\n\nlogging:\n level: \"INFO\" # \u65e5\u5fd7\u7ea7\u522b\uff1aDEBUG\/INFO\/WARNING\/ERROR\n format: \"standard\" # \u65e5\u5fd7\u683c\u5f0f\uff1astandard\/json\n file: \"logs\/app.log\" # \u65e5\u5fd7\u6587\u4ef6\u8def\u5f84\n\nsecurity:\n max_upload_size: 10485760 # \u6700\u5927\u4e0a\u4f20\u6587\u4ef6\u5927\u5c0f\uff08\u5b57\u8282\uff0c\u9ed8\u8ba4 10MB\uff09\n password_min_length: 8 # \u5bc6\u7801\u6700\u5c0f\u957f\u5ea6\n session_ttl: 86400 # Session \u8fc7\u671f\u65f6\u95f4\uff08\u79d2\uff0c\u9ed8\u8ba4 1 \u5929\uff09\n\nretry:\n count: 3 # \u8bf7\u6c42\u5931\u8d25\u91cd\u8bd5\u6b21\u6570\n backoff: 1.5 # \u9000\u907f\u4e58\u6570\n max_delay: 60.0 # \u6700\u5927\u91cd\u8bd5\u5ef6\u8fdf\uff08\u79d2\uff09\n<\/pre>\n\n<h3>6.3 \u914d\u7f6e\u52a0\u8f7d\u4e0e\u5408\u5e76<\/h3>\n<pre class=\"code-block\">import yaml\nfrom pathlib import Path\nfrom typing import Any\nimport os\n\n\ndef load_config(env: str | None = None) -> dict[str, Any]:\n \"\"\"\u52a0\u8f7d\u914d\u7f6e\uff0c\u6309\u4f18\u5148\u7ea7\u5408\u5e76\u3002\"\"\"\n config_dir = Path(\"config\")\n\n # 1. \u52a0\u8f7d\u9ed8\u8ba4\u503c\n default_path = config_dir \/ \"default.yaml\"\n config = yaml.safe_load(default_path.read_text(encoding=\"utf-8\"))\n\n # 2. \u52a0\u8f7d\u73af\u5883\u7279\u5b9a\u914d\u7f6e\uff08\u5982\u5b58\u5728\uff09\n env = env or os.getenv(\"APP_ENV\", \"dev\")\n env_path = config_dir \/ f\"{env}.yaml\"\n if env_path.exists():\n env_config = yaml.safe_load(env_path.read_text(encoding=\"utf-8\"))\n config = deep_merge(config, env_config)\n\n return config\n\n\ndef deep_merge(base: dict, override: dict) -> dict:\n \"\"\"\u6df1\u5ea6\u5408\u5e76\u4e24\u4e2a\u5b57\u5178\uff0coverride \u4f18\u5148\u3002\"\"\"\n result = base.copy()\n for key, value in override.items():\n if key in result and isinstance(result[key], dict) and isinstance(value, dict):\n result[key] = deep_merge(result[key], value)\n else:\n result[key] = value\n return result\n<\/pre>\n\n\n<h2 id=\"zh-7\">\u4e03\u3001\u4e0d\u540c\u73af\u5883\u7684\u9ed8\u8ba4\u503c\u8986\u76d6<\/h2>\n\n<h3>7.1 \u73af\u5883\u914d\u7f6e\u5dee\u5f02\u8868<\/h3>\n<div class=\"table-wrap\">\n<table>\n <thead>\n <tr><th>\u914d\u7f6e\u9879<\/th><th>default.yaml<\/th><th>dev.yaml<\/th><th>test.yaml<\/th><th>prod.yaml<\/th><\/tr>\n <\/thead>\n <tbody>\n <tr><td>debug<\/td><td>false<\/td><td>true<\/td><td>false<\/td><td>false<\/td><\/tr>\n <tr><td>server.workers<\/td><td>4<\/td><td>1<\/td><td>2<\/td><td>8<\/td><\/tr>\n <tr><td>database.host<\/td><td>localhost<\/td><td>localhost<\/td><td>test-db<\/td><td>prod-db.internal<\/td><\/tr>\n <tr><td>database.pool_size<\/td><td>10<\/td><td>5<\/td><td>5<\/td><td>50<\/td><\/tr>\n <tr><td>log.level<\/td><td>INFO<\/td><td>DEBUG<\/td><td>DEBUG<\/td><td>INFO<\/td><\/tr>\n <tr><td>cache.enabled<\/td><td>true<\/td><td>false<\/td><td>false<\/td><td>true<\/td><\/tr>\n <tr><td>retry.count<\/td><td>3<\/td><td>1<\/td><td>0<\/td><td>5<\/td><\/tr>\n <\/tbody>\n<\/table>\n<\/div>\n\n<h3>7.2 \u73af\u5883\u7279\u5b9a\u914d\u7f6e\u793a\u4f8b<\/h3>\n<pre class=\"code-block\"># config\/dev.yaml\n# \u5f00\u53d1\u73af\u5883\uff1a\u8c03\u8bd5\u53cb\u597d\uff0c\u6027\u80fd\u6b21\u8981\n\nserver:\n workers: 1 # \u5355\u8fdb\u7a0b\uff0c\u65b9\u4fbf\u65ad\u70b9\u8c03\u8bd5\n reload: true # \u4ee3\u7801\u53d8\u66f4\u81ea\u52a8\u91cd\u542f\n\ndatabase:\n pool_size: 5 # \u672c\u5730\u6570\u636e\u5e93\u538b\u529b\u5c0f\n echo: true # \u6253\u5370 SQL \u8bed\u53e5\n\nlogging:\n level: \"DEBUG\" # \u5f00\u53d1\u9700\u8981\u8be6\u7ec6\u65e5\u5fd7\n\ncache:\n enabled: false # \u5f00\u53d1\u65f6\u907f\u514d\u7f13\u5b58\u5e72\u6270\u8c03\u8bd5\n\n# config\/prod.yaml\n# \u751f\u4ea7\u73af\u5883\uff1a\u6027\u80fd\u4f18\u5148\uff0c\u5b89\u5168\u4fdd\u5b88\n\nserver:\n workers: 8 # \u591a\u8fdb\u7a0b\u5904\u7406\u5e76\u53d1\n reload: false # \u7981\u6b62\u81ea\u52a8\u91cd\u542f\n\ndatabase:\n pool_size: 50 # \u652f\u6491\u9ad8\u5e76\u53d1\n echo: false # \u5173\u95ed SQL \u6253\u5370\n\nlogging:\n level: \"INFO\" # \u51cf\u5c11\u65e5\u5fd7\u91cf\n\ncache:\n enabled: true # \u542f\u7528\u7f13\u5b58\u63d0\u5347\u6027\u80fd\n\nretry:\n count: 5 # \u7f51\u7edc\u4e0d\u7a33\u5b9a\u65f6\u66f4\u591a\u91cd\u8bd5\n<\/pre>\n\n\n<h2 id=\"zh-8\">\u516b\u3001\u9ed8\u8ba4\u503c\u53d8\u66f4\u4e0e\u7248\u672c\u7ba1\u7406<\/h2>\n\n<h3>8.1 \u9ed8\u8ba4\u503c\u53d8\u66f4\u7684\u5f71\u54cd<\/h3>\n<div class=\"info-box warn\">\n <strong>\u4fee\u6539\u9ed8\u8ba4\u503c\u662f\u6f5c\u5728\u7684\u7834\u574f\u6027\u53d8\u66f4\uff08Breaking Change\uff09\u3002\u5373\u4f7f\u4ee3\u7801\u6ca1\u6539\uff0c\u884c\u4e3a\u53ef\u80fd\u5df2\u53d8\u3002\u53d8\u66f4\u9ed8\u8ba4\u503c\u5fc5\u987b\u9075\u5faa\u7248\u672c\u7ba1\u7406\u89c4\u8303\u3002<\/strong>\n<\/div>\n\n<h3>8.2 \u53d8\u66f4\u89c4\u8303<\/h3>\n<div class=\"card\">\n <h4>\u9ed8\u8ba4\u503c\u53d8\u66f4\u4e09\u6761\u89c4\u5219<\/h4>\n <p>1. <span class=\"tag tag-r\">\u6587\u6863\u5148\u884c<\/span> \u4fee\u6539\u9ed8\u8ba4\u503c\u524d\uff0c\u5728 CHANGELOG \u4e2d\u8bf4\u660e\u53d8\u66f4\u539f\u56e0\u548c\u5f71\u54cd\u8303\u56f4<\/p>\n <p>2. <span class=\"tag tag-b\">\u7248\u672c\u6807\u8bb0<\/span> \u9ed8\u8ba4\u503c\u53d8\u66f4\u968f\u529f\u80fd\u53d1\u5e03\uff0c\u8bed\u4e49\u5316\u7248\u672c\uff1a\u529f\u80fd\u65b0\u589e\u7528 MINOR\uff0c\u9ed8\u8ba4\u503c\u5927\u5e45\u53d8\u66f4\u9700\u8bc4\u4f30\u662f\u5426 MAJOR<\/p>\n <p>3. <span class=\"tag tag-g\">\u517c\u5bb9\u6027\u8fc7\u6e21<\/span> \u91cd\u8981\u9ed8\u8ba4\u503c\u53d8\u66f4\u63d0\u4f9b\u8fc7\u6e21\u671f\uff1a\u65e7\u503c\u5e9f\u5f03\u8b66\u544a\uff0c\u4e0b\u4e00\u7248\u672c\u518d\u5207\u6362<\/p>\n<\/div>\n\n<pre class=\"code-block\"># \u8fc7\u6e21\u671f\u517c\u5bb9\u793a\u4f8b\nimport warnings\n\ndef connect_to_database(timeout: float | None = None) -> Connection:\n \"\"\"\u8fde\u63a5\u6570\u636e\u5e93\u3002\n\n Args:\n timeout: \u8fde\u63a5\u8d85\u65f6\uff08\u79d2\uff09\u3002\u9ed8\u8ba4 30 \u79d2\u3002\n \u6ce8\uff1a\u65e7\u9ed8\u8ba4\u503c 60 \u79d2\u5c06\u5728 v2.0 \u79fb\u9664\u3002\n \"\"\"\n if timeout is None:\n timeout = 30.0 # \u65b0\u9ed8\u8ba4\u503c\n elif timeout == 60.0:\n warnings.warn(\n \"\u9ed8\u8ba4\u8d85\u65f6\u5df2\u4ece 60 \u79d2\u6539\u4e3a 30 \u79d2\uff0c\"\n \"\u663e\u5f0f\u4f20\u5165 timeout=60 \u4ee5\u4fdd\u6301\u65e7\u884c\u4e3a\u3002\",\n DeprecationWarning,\n stacklevel=2\n )\n return _create_connection(timeout)\n<\/pre>\n\n\n<h2 id=\"zh-9\">\u4e5d\u3001\u9ed8\u8ba4\u503c\u4f7f\u7528\u6700\u4f73\u5b9e\u8df5<\/h2>\n\n<h3>9.1 \u6700\u4f73\u5b9e\u8df5\u6e05\u5355<\/h3>\n<div class=\"card\">\n <h4>\u8bbe\u8ba1\u4e0e\u5b9e\u73b0\u89c4\u8303<\/h4>\n <p>\u2705 <strong>\u5355\u4e00\u6570\u636e\u6e90<\/strong> \u6240\u6709\u9ed8\u8ba4\u503c\u96c6\u4e2d\u5728\u4e00\u4e2a\u6587\u4ef6\uff08defaults.py \u6216 default.yaml\uff09\uff0c\u7981\u6b62\u6563\u843d\u5728\u5404\u5904<\/p>\n <p>\u2705 <strong>\u547d\u540d\u5e38\u91cf<\/strong> \u7528\u6709\u610f\u4e49\u7684\u540d\u79f0\u66ff\u4ee3\u9b54\u6cd5\u6570\u5b57\uff0c\u5982 <code>DEFAULT_TIMEOUT = 30<\/code> \u800c\u975e <code>30<\/code><\/p>\n <p>\u2705 <strong>\u7c7b\u578b\u6ce8\u89e3<\/strong> \u4e3a\u6240\u6709\u9ed8\u8ba4\u503c\u6dfb\u52a0\u7c7b\u578b\u6ce8\u89e3\uff0c\u4fbf\u4e8e\u9759\u6001\u68c0\u67e5\u548c IDE \u63d0\u793a<\/p>\n <p>\u2705 <strong>\u5355\u4f4d\u6807\u6ce8<\/strong> \u65f6\u95f4\/\u5927\u5c0f\u7c7b\u9ed8\u8ba4\u503c\u5728\u6ce8\u91ca\u4e2d\u6ce8\u660e\u5355\u4f4d\uff08\u79d2\u3001\u5b57\u8282\u3001\u6beb\u79d2\uff09<\/p>\n <p>\u2705 <strong>\u8303\u56f4\u6821\u9a8c<\/strong> \u5bf9\u6570\u503c\u578b\u9ed8\u8ba4\u503c\u8bbe\u7f6e\u5408\u7406\u7684\u4e0a\u4e0b\u754c\uff08Pydantic Field \u7684 ge\/le\uff09<\/p>\n <p>\u2705 <strong>\u73af\u5883\u9694\u79bb<\/strong> \u4e0d\u540c\u73af\u5883\u7684\u8986\u76d6\u914d\u7f6e\u5355\u72ec\u5b58\u653e\uff0cdefault \u504f\u4fdd\u5b88\uff0c\u751f\u4ea7\u6309\u9700\u653e\u5927<\/p>\n <p>\u2705 <strong>\u5411\u540e\u517c\u5bb9<\/strong> \u65b0\u589e\u914d\u7f6e\u9879\u5fc5\u987b\u6709\u9ed8\u8ba4\u503c\uff0c\u786e\u4fdd\u8001\u7528\u6237\u65e0\u9700\u4fee\u6539\u5373\u53ef\u5347\u7ea7<\/p>\n <p>\u2705 <strong>\u5b9a\u671f\u5ba1\u8ba1<\/strong> \u6bcf\u5b63\u5ea6 Review \u9ed8\u8ba4\u503c\u662f\u5426\u4ecd\u7b26\u5408\u5f53\u524d\u7cfb\u7edf\u89c4\u6a21\u548c\u6700\u4f73\u5b9e\u8df5<\/p>\n<\/div>\n\n<h3>9.2 \u9ed8\u8ba4\u503c Review Checklist<\/h3>\n<pre class=\"code-block\"># \u4ee3\u7801 Review \u65f6\u68c0\u67e5\u9ed8\u8ba4\u503c\n\u25a1 \u9ed8\u8ba4\u503c\u662f\u5426\u6765\u81ea defaults.py\uff08\u800c\u975e\u9b54\u6cd5\u6570\u5b57\uff09\n\u25a1 \u9ed8\u8ba4\u503c\u662f\u5426\u7ecf\u8fc7\u751f\u4ea7\u9a8c\u8bc1\uff08\u800c\u975e\u62cd\u8111\u888b\uff09\n\u25a1 \u5e03\u5c14\u9ed8\u8ba4\u503c\u8bed\u4e49\u662f\u5426\u6e05\u6670\uff08\u662f\u5426\u9700\u8981\u679a\u4e3e\u66ff\u4ee3\uff09\n\u25a1 \u65f6\u95f4\/\u5927\u5c0f\u7c7b\u662f\u5426\u6709\u5355\u4f4d\u6ce8\u91ca\n\u25a1 \u53ef\u53d8\u5bf9\u8c61\u662f\u5426\u4f7f\u7528\u4e86 None \u54e8\u5175\uff08\u907f\u514d\u5171\u4eab\u72b6\u6001\uff09\n\u25a1 \u65b0\u589e\u914d\u7f6e\u9879\u662f\u5426\u6709\u9ed8\u8ba4\u503c\uff08\u5411\u540e\u517c\u5bb9\uff09\n\u25a1 \u9ed8\u8ba4\u503c\u53d8\u66f4\u662f\u5426\u5728 CHANGELOG \u4e2d\u8bb0\u5f55\n\u25a1 \u654f\u611f\u914d\u7f6e\uff08\u5bc6\u7801\u3001\u5bc6\u94a5\uff09\u662f\u5426\u6ca1\u6709\u9ed8\u8ba4\u503c\uff08\u5f3a\u5236\u7528\u6237\u586b\u5199\uff09\n<\/pre>\n\n\n<h2 id=\"zh-10\">\u5341\u3001\u5e38\u89c1\u95ee\u9898\u4e0e\u6392\u67e5<\/h2>\n\n<div class=\"table-wrap\">\n<table>\n <thead>\n <tr><th>\u95ee\u9898\u73b0\u8c61<\/th><th>\u539f\u56e0<\/th><th>\u89e3\u51b3\u65b9\u6848<\/th><\/tr>\n <\/thead>\n <tbody>\n <tr>\n <td>\u9ed8\u8ba4\u503c\u672a\u751f\u6548<\/td>\n <td>\u52a0\u8f7d\u987a\u5e8f\u9519\u8bef\uff0c\u73af\u5883\u53d8\u91cf\u6216\u914d\u7f6e\u6587\u4ef6\u8986\u76d6\u4e86\u9ed8\u8ba4\u503c\u4f46\u672a\u6ce8\u610f<\/td>\n <td>\u6253\u5370\u6700\u7ec8\u914d\u7f6e\uff0c\u786e\u8ba4\u5404\u5c42\u7ea7\u52a0\u8f7d\u7ed3\u679c\uff1b\u4f7f\u7528 Pydantic Settings \u81ea\u52a8\u8ffd\u8e2a<\/td>\n <\/tr>\n <tr>\n <td>\u4e0d\u540c\u673a\u5668\u884c\u4e3a\u4e0d\u4e00\u81f4<\/td>\n <td>\u672c\u5730\u6709\u672a\u63d0\u4ea4\u7684 dev.yaml\uff0c\u5176\u4ed6\u4eba\u6ca1\u6709<\/td>\n <td>.gitignore \u6392\u9664\u672c\u5730\u8986\u76d6\u6587\u4ef6\uff0c\u56e2\u961f\u5171\u4eab\u914d\u7f6e\u901a\u8fc7\u73af\u5883\u53d8\u91cf\u6216\u7edf\u4e00\u914d\u7f6e\u4e2d\u5fc3<\/td>\n <\/tr>\n <tr>\n <td>\u9ed8\u8ba4\u503c\u53d8\u66f4\u5bfc\u81f4\u7ebf\u4e0a\u6545\u969c<\/td>\n <td>\u5347\u7ea7\u7248\u672c\u65f6\u672a\u6ce8\u610f\u5230\u9ed8\u8ba4\u503c\u5df2\u4fee\u6539<\/td>\n <td>CHANGELOG \u9192\u76ee\u6807\u6ce8 Breaking Changes\uff1b\u5347\u7ea7\u524d diff \u914d\u7f6e\u53d8\u66f4<\/td>\n <\/tr>\n <tr>\n <td>\u914d\u7f6e\u9879\u592a\u591a\u96be\u4ee5\u7ba1\u7406<\/td>\n <td>\u7f3a\u4e4f\u5206\u5c42\uff0c\u6240\u6709\u914d\u7f6e\u5e73\u94fa\u5728\u4e00\u4e2a\u6587\u4ef6<\/td>\n <td>\u6309\u6a21\u5757\u5206\u7ec4\uff08server\/database\/cache\/logging\uff09\uff0c\u5fc5\u8981\u65f6\u62c6\u5206\u5b50\u914d\u7f6e\u7c7b<\/td>\n <\/tr>\n <tr>\n <td>\u5bc6\u7801\u7b49\u6709\u9ed8\u8ba4\u503c\u5bfc\u81f4\u5b89\u5168\u98ce\u9669<\/td>\n <td>\u654f\u611f\u914d\u7f6e\u8bbe\u7f6e\u4e86\u9ed8\u8ba4\u503c\uff0c\u7528\u6237\u672a\u8986\u76d6<\/td>\n <td>\u654f\u611f\u914d\u7f6e\u4e0d\u8bbe\u9ed8\u8ba4\u503c\uff0c\u542f\u52a8\u65f6\u5f3a\u5236\u6821\u9a8c\u7f3a\u5931\u5373\u62a5\u9519<\/td>\n <\/tr>\n <tr>\n <td>\u9ed8\u8ba4\u503c\u7c7b\u578b\u9519\u8bef<\/td>\n <td>\u73af\u5883\u53d8\u91cf\u90fd\u662f\u5b57\u7b26\u4e32\uff0c\u672a\u6b63\u786e\u8f6c\u6362<\/td>\n <td>\u4f7f\u7528 Pydantic \u81ea\u52a8\u8f6c\u6362\uff0c\u6216\u663e\u5f0f int()\/float()\/bool() \u8f6c\u6362<\/td>\n <\/tr>\n <\/tbody>\n<\/table>\n<\/div>\n\n<h3>\u5feb\u901f\u6392\u67e5\u547d\u4ee4<\/h3>\n<pre class=\"terminal\"><span class=\"comment\"># \u67e5\u770b\u5f53\u524d\u751f\u6548\u7684\u6240\u6709\u914d\u7f6e<\/span>\n<span class=\"prompt\">python -c<\/span> \"from myapp.config import config; print(config.model_dump_json(indent=2))\"\n\n<span class=\"comment\"># \u67e5\u770b\u67d0\u4e2a\u914d\u7f6e\u7684\u6765\u6e90<\/span>\n<span class=\"prompt\">python -c<\/span> \"from myapp.config import config; print(config.port)\n<span class=\"output\">8000<\/span>\n\n<span class=\"comment\"># \u68c0\u67e5\u73af\u5883\u53d8\u91cf\u662f\u5426\u8986\u76d6<\/span>\n<span class=\"prompt\">$env:APP_PORT<\/span>\n<span class=\"output\">9000 # \u73af\u5883\u53d8\u91cf\u8986\u76d6\u4e86\u9ed8\u8ba4\u503c<\/span>\n<\/pre>\n\n<div class=\"info-box\">\n <strong>\u5168\u6d41\u7a0b\u603b\u7ed3\uff1a\u7406\u89e3\u9ed8\u8ba4\u503c\u964d\u4f4e\u95e8\u69db\u548c\u9632\u5fa1\u7f16\u7a0b\u7684\u4ef7\u503c \u2192 \u5c06\u9ed8\u8ba4\u503c\u96c6\u4e2d\u7ba1\u7406\uff08\u5355\u4e00\u6570\u636e\u6e90\uff09\u2192 \u4f7f\u7528 Pydantic\/dataclasses \u5b9e\u73b0\u7c7b\u578b\u5b89\u5168 \u2192 \u914d\u7f6e\u6587\u4ef6\u5206\u5c42\uff08default + env-specific\uff09\u2192 \u73af\u5883\u53d8\u91cf\u53ef\u8986\u76d6 \u2192 \u53d8\u66f4\u65f6\u6587\u6863\u5316\u5e76\u8003\u8651\u517c\u5bb9\u6027 \u2192 \u5b9a\u671f\u5ba1\u8ba1\u9ed8\u8ba4\u503c\u5408\u7406\u6027\u3002\u597d\u7684\u9ed8\u8ba4\u503c\u8ba9\u7cfb\u7edf\u65e2\u7075\u6d3b\u53c8\u7a33\u5065\u3002<\/strong>\n<\/div>\n\n<\/div>\n\n\n<div class=\"lang-section\" id=\"lang-en\">\n<div class=\"hero\">\n <h1>Default Values Management Complete Guide<span class=\"sub\">Why We Need Them & How to Manage Them Systematically<\/span><\/h1>\n <p>Why defaults matter, application scenarios, common pitfalls, unified management strategies, Python implementation patterns, config layering, environment overrides, versioning & best practices<\/p>\n<\/div>\n\n<div class=\"toc\">\n <h3>Table of Contents<\/h3>\n <ol>\n <li><a href=\"#en-1\">1 Why We Need Default Values<\/a><\/li>\n <li><a href=\"#en-2\">2 Application Scenarios<\/a><\/li>\n <li><a href=\"#en-3\">3 Common Pitfalls<\/a><\/li>\n <li><a href=\"#en-4\">4 Unified Management Strategy<\/a><\/li>\n <li><a href=\"#en-5\">5 Python Implementation Patterns<\/a><\/li>\n <li><a href=\"#en-6\">6 Config File Layering<\/a><\/li>\n <li><a href=\"#en-7\">7 Environment-Specific Overrides<\/a><\/li>\n <li><a href=\"#en-8\">8 Changing Defaults & Versioning<\/a><\/li>\n <li><a href=\"#en-9\">9 Best Practices<\/a><\/li>\n <li><a href=\"#en-10\">10 FAQ & Troubleshooting<\/a><\/li>\n <\/ol>\n<\/div>\n\n<h2 id=\"en-1\">1 Why We Need Default Values<\/h2>\n\n<div class=\"card\">\n <h4>Five Core Values<\/h4>\n <p><span class=\"tag tag-b\">Lower Barrier<\/span> New users can run without learning all details<\/p>\n <p><span class=\"tag tag-g\">Defensive Coding<\/span> Prevent runtime errors from missing config<\/p>\n <p><span class=\"tag tag-y\">Unified Standards<\/span> Team shares validated baseline configurations<\/p>\n <p><span class=\"tag tag-p\">Backward Compatible<\/span> Existing users upgrade smoothly without changes<\/p>\n <p><span class=\"tag tag-r\">Safety Net<\/span> Conservative defaults for timeouts, retries prevent incidents<\/p>\n<\/div>\n\n<div class=\"info-box\">\n <strong>Core Principle: Default values are not “random guesses” but “team-vetted, production-tested recommendations.” Good defaults let 80% of users run without tuning, while 20% power users can override explicitly.<\/strong>\n<\/div>\n\n<h2 id=\"en-2\">2 Application Scenarios<\/h2>\n\n<div class=\"table-wrap\">\n<table>\n <thead><tr><th>Scope<\/th><th>Example<\/th><th>Management<\/th><\/tr><\/thead>\n <tbody>\n <tr><td>Language-level<\/td><td>Function params <code>def fn(x=10)<\/code><\/td><td>Hard-coded<\/td><\/tr>\n <tr><td>Module-level<\/td><td>DB pool size, HTTP timeout<\/td><td>Module constants<\/td><\/tr>\n <tr><td>Project-level<\/td><td>Server port, log level<\/td><td>Config file \/ env vars<\/td><\/tr>\n <tr><td>Environment-level<\/td><td>Prod vs dev DB host<\/td><td>Env vars \/ layered config<\/td><\/tr>\n <tr><td>User-level<\/td><td>Preferences, theme<\/td><td>User config \/ database<\/td><\/tr>\n <\/tbody>\n<\/table>\n<\/div>\n\n<h2 id=\"en-3\">3 Common Pitfalls<\/h2>\n\n<h3>Mutable Default Argument Trap<\/h3>\n<div class=\"compare-box\">\n <div class=\"compare-col bad\">\n <h4>\u274c Wrong<\/h4>\n<pre class=\"example\">def append_item(item, items=[]):\n items.append(item)\n return items\n\nprint(append_item(1)) # [1]\nprint(append_item(2)) # [1, 2] \u2190 surprise!<\/pre>\n <\/div>\n <div class=\"compare-col good\">\n <h4>\u2705 Correct<\/h4>\n<pre class=\"example\">def append_item(item, items=None):\n if items is None:\n items = []\n items.append(item)\n return items<\/pre>\n <\/div>\n<\/div>\n\n<h2 id=\"en-4\">4 Unified Management Strategy<\/h2>\n\n<div class=\"flow-diagram\">\n <div class=\"flow-row\">\n <span class=\"flow-item green\">defaults.py<\/span>\n <span class=\"flow-arrow\">←<\/span>\n <span class=\"flow-item\">Single Source of Truth<\/span>\n <span class=\"flow-arrow\">→<\/span>\n <span class=\"flow-item yellow\">Config File<\/span>\n <span class=\"flow-arrow\">→<\/span>\n <span class=\"flow-item purple\">Env Vars<\/span>\n <span class=\"flow-arrow\">→<\/span>\n <span class=\"flow-item\">Runtime Override<\/span>\n <\/div>\n<\/div>\n\n<div class=\"info-box\">\n <strong>Priority: Runtime args > Env vars > Config file > Code defaults. Every layer falls back to code defaults.<\/strong>\n<\/div>\n\n<h2 id=\"en-5\">5 Python Implementation Patterns<\/h2>\n\n<h3>Pattern 1: Constants Module<\/h3>\n<pre class=\"code-block\"># defaults.py\nDEFAULT_HOST: str = \"0.0.0.0\"\nDEFAULT_PORT: int = 8000\nDEFAULT_TIMEOUT: float = 30.0\nDEFAULT_DB_POOL_SIZE: int = 10\n<\/pre>\n\n<h3>Pattern 2: Pydantic Settings (Recommended)<\/h3>\n<pre class=\"code-block\">from pydantic import Field\nfrom pydantic_settings import BaseSettings, SettingsConfigDict\n\nclass AppConfig(BaseSettings):\n model_config = SettingsConfigDict(env_file=\".env\")\n port: int = Field(default=8000, ge=1, le=65535)\n workers: int = Field(default=4, ge=1)\n timeout: float = Field(default=30.0, gt=0)\n\nconfig = AppConfig() # Auto loads from env vars\n<\/pre>\n\n<h3>Pattern 3: dataclasses + Merge<\/h3>\n<pre class=\"code-block\">from dataclasses import dataclass, field\n\n@dataclass\nclass AppConfig:\n env: str = \"dev\"\n debug: bool = False\n server_port: int = 8000\n\n @classmethod\n def from_env(cls) -> \"AppConfig\":\n cfg = cls()\n if \"APP_PORT\" in os.environ:\n cfg.server_port = int(os.environ[\"APP_PORT\"])\n return cfg\n<\/pre>\n\n<h2 id=\"en-6\">6 Config File Layering<\/h2>\n\n<pre class=\"code-block\">config\/\n\u251c\u2500\u2500 default.yaml # All defaults, committed to Git\n\u251c\u2500\u2500 default.yaml.example # Template with explanations\n\u251c\u2500\u2500 dev.yaml # Dev overrides (optional, .gitignore)\n\u251c\u2500\u2500 test.yaml # Test overrides\n\u2514\u2500\u2500 prod.yaml # Production overrides (CI\/CD injected)\n<\/pre>\n\n<h3>Loading & Merging<\/h3>\n<pre class=\"code-block\">def load_config(env: str | None = None) -> dict:\n config = yaml.safe_load(Path(\"config\/default.yaml\").read_text())\n env = env or os.getenv(\"APP_ENV\", \"dev\")\n env_path = Path(f\"config\/{env}.yaml\")\n if env_path.exists():\n env_config = yaml.safe_load(env_path.read_text())\n config = deep_merge(config, env_config)\n return config\n<\/pre>\n\n<h2 id=\"en-7\">7 Environment-Specific Overrides<\/h2>\n\n<div class=\"table-wrap\">\n<table>\n <thead><tr><th>Setting<\/th><th>default<\/th><th>dev<\/th><th>test<\/th><th>prod<\/th><\/tr><\/thead>\n <tbody>\n <tr><td>debug<\/td><td>false<\/td><td>true<\/td><td>false<\/td><td>false<\/td><\/tr>\n <tr><td>workers<\/td><td>4<\/td><td>1<\/td><td>2<\/td><td>8<\/td><\/tr>\n <tr><td>db.pool_size<\/td><td>10<\/td><td>5<\/td><td>5<\/td><td>50<\/td><\/tr>\n <tr><td>log.level<\/td><td>INFO<\/td><td>DEBUG<\/td><td>DEBUG<\/td><td>INFO<\/td><\/tr>\n <tr><td>cache.enabled<\/td><td>true<\/td><td>false<\/td><td>false<\/td><td>true<\/td><\/tr>\n <\/tbody>\n<\/table>\n<\/div>\n\n<h2 id=\"en-8\">8 Changing Defaults & Versioning<\/h2>\n\n<div class=\"info-box warn\">\n <strong>Changing a default is a potential Breaking Change. Even if code doesn’t change, behavior might. Follow versioning rules.<\/strong>\n<\/div>\n\n<div class=\"card\">\n <h4>Three Rules for Changing Defaults<\/h4>\n <p>1. <span class=\"tag tag-r\">Document First<\/span> Update CHANGELOG before changing<\/p>\n <p>2. <span class=\"tag tag-b\">Version Tag<\/span> Follow semver: minor for additions, major for breaking default changes<\/p>\n <p>3. <span class=\"tag tag-g\">Transition Period<\/span> Deprecate old value with warnings, switch in next version<\/p>\n<\/div>\n\n<h2 id=\"en-9\">9 Best Practices<\/h2>\n\n<div class=\"card\">\n <h4>Best Practices Checklist<\/h4>\n <p>\u2705 <strong>Single Source<\/strong> Centralize all defaults in one file<\/p>\n <p>\u2705 <strong>Named Constants<\/strong> Use <code>DEFAULT_TIMEOUT = 30<\/code> not magic numbers<\/p>\n <p>\u2705 <strong>Type Annotations<\/strong> Annotate all defaults for static checking<\/p>\n <p>\u2705 <strong>Unit Comments<\/strong> Document units (seconds, bytes, ms)<\/p>\n <p>\u2705 <strong>Bounds Check<\/strong> Set min\/max for numeric defaults<\/p>\n <p>\u2705 <strong>Environment Isolation<\/strong> Separate override configs per environment<\/p>\n <p>\u2705 <strong>Backward Compatible<\/strong> New config items must have defaults<\/p>\n <p>\u2705 <strong>Periodic Audit<\/strong> Review defaults quarterly<\/p>\n<\/div>\n\n<h2 id=\"en-10\">10 FAQ & Troubleshooting<\/h2>\n\n<div class=\"table-wrap\">\n<table>\n <thead><tr><th>Issue<\/th><th>Solution<\/th><\/tr><\/thead>\n <tbody>\n <tr><td>Default not applied<\/td><td>Check loading order; print final config to verify<\/td><\/tr>\n <tr><td>Inconsistent behavior across machines<\/td><td>.gitignore local override files; use env vars for team sharing<\/td><\/tr>\n <tr><td>Default change caused incident<\/td><td>Highlight breaking changes in CHANGELOG; diff configs before upgrade<\/td><\/tr>\n <tr><td>Too many configs to manage<\/td><td>Group by module (server\/db\/cache\/logging); use sub-config classes<\/td><\/tr>\n <tr><td>Security risk from default passwords<\/td><td>Never set defaults for secrets; fail on startup if missing<\/td><\/tr>\n <tr><td>Default type mismatch<\/td><td>Use Pydantic for auto-conversion, or explicit int()\/bool()<\/td><\/tr>\n <\/tbody>\n<\/table>\n<\/div>\n\n<div class=\"info-box\">\n <strong>Summary: Understand defaults lower barriers and provide safety nets \u2192 Centralize management (single source of truth) \u2192 Use Pydantic\/dataclasses for type safety \u2192 Layer configs (default + env-specific) \u2192 Allow env var overrides \u2192 Document changes with compatibility consideration \u2192 Audit defaults periodically. Good defaults make systems both flexible and robust.<\/strong>\n<\/div>\n\n<\/div>\n<\/main>\n\n<footer>\n <div class=\"links\">\n <a href=\"https:\/\/docs.pydantic.dev\/latest\/concepts\/pydantic_settings\/\" target=\"_blank\" rel=\"noopener\">Pydantic Settings<\/a>\n <a href=\"https:\/\/12factor.net\/config\" target=\"_blank\" rel=\"noopener\">12-Factor Config<\/a>\n <a href=\"https:\/\/docs.python.org\/3\/library\/argparse.html\" target=\"_blank\" rel=\"noopener\">argparse Docs<\/a>\n <\/div>\n <p>Default Values Management Complete Guide<\/p>\n<\/footer>\n\n<script>\nfunction setLang(lang){\n document.querySelectorAll('.lang-section').forEach(el=>el.classList.remove('active'));\n document.getElementById('lang-'+lang).classList.add('active');\n document.querySelectorAll('.lang-switch button').forEach(btn=>btn.classList.remove('active'));\n document.getElementById('btn-'+lang).classList.add('active');\n document.documentElement.lang = lang==='zh'?'zh-CN':'en';\n const prefix = lang==='zh'?'zh':'en';\n const newHash = window.location.hash.replace(\/^#(zh|en)-\/, prefix+\"-\");\n if(newHash) window.location.hash = newHash;\n}\nfunction toggleTheme(){\n const html = document.documentElement;\n if(html.hasAttribute('data-theme')){\n html.removeAttribute('data-theme');\n localStorage.removeItem('theme');\n }else{\n html.setAttribute('data-theme','dark');\n localStorage.setItem('theme','dark');\n }\n}\n(function(){\n if(localStorage.getItem('theme')==='dark') document.documentElement.setAttribute('data-theme','dark');\n const hash = window.location.hash;\n if(hash){\n const target = document.querySelector(hash);\n if(target) setTimeout(()=>target.scrollIntoView({behavior:'smooth'}),100);\n }\n})();\n<\/script>\n<\/body>\n<\/html>\n","protected":false},"excerpt":{"rendered":"<p>\u9ed8\u8ba4\u503c\u7ba1\u7406\u5b8c\u6574\u6307\u5357 \u00b7 Default Values Management Guide \u2699\ufe0f \u9ed8\u8ba4\u503c\u7ba1\u7406\u5b8c\u6574\u6307 […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[11,9],"tags":[],"class_list":["post-361","post","type-post","status-publish","format-standard","hentry","category-cad","category-ai"],"blocksy_meta":[],"_links":{"self":[{"href":"https:\/\/numsimlab.com\/index.php?rest_route=\/wp\/v2\/posts\/361","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/numsimlab.com\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/numsimlab.com\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/numsimlab.com\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/numsimlab.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=361"}],"version-history":[{"count":1,"href":"https:\/\/numsimlab.com\/index.php?rest_route=\/wp\/v2\/posts\/361\/revisions"}],"predecessor-version":[{"id":362,"href":"https:\/\/numsimlab.com\/index.php?rest_route=\/wp\/v2\/posts\/361\/revisions\/362"}],"wp:attachment":[{"href":"https:\/\/numsimlab.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=361"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/numsimlab.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=361"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/numsimlab.com\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=361"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}

{"id":361,"date":"2026-07-16T17:03:05","date_gmt":"2026-07-16T09:03:05","guid":{"rendered":"https:\/\/numsimlab.com\/?p=361"},"modified":"2026-07-16T17:03:05","modified_gmt":"2026-07-16T09:03:05","slug":"%e9%bb%98%e8%ae%a4%e5%80%bc%e7%ae%a1%e7%90%86%e5%ae%8c%e6%95%b4%e6%8c%87%e5%8d%97","status":"publish","type":"post","link":"https:\/\/numsimlab.com\/?p=361","title":{"rendered":"\u9ed8\u8ba4\u503c\u7ba1\u7406\u5b8c\u6574\u6307\u5357"},"content":{"rendered":"\n\n\n\n\n\n\u9ed8\u8ba4\u503c\u7ba1\u7406\u5b8c\u6574\u6307\u5357 \u00b7 Default Values Management Guide<\/title>\n<style>\n*,*::before,*::after{box-sizing:border-box;margin:0;padding:0}\nhtml{scroll-behavior:smooth}\n:root{\n --bg:#f8f9fa;--bg2:#fff;--ink:#1a1a2e;--muted:#6c7086;--rule:#e2e4eb;\n --accent:#2563eb;--accent2:#16a34a;--accent3:#dc2626;--accent4:#d97706;--accent5:#7c3aed;\n --card-bg:#fff;--code-bg:#f1f3f5;\n --tag-g:#dcfce7;--tag-g-t:#166534;--tag-b:#dbeafe;--tag-b-t:#1e40af;\n --tag-r:#fee2e2;--tag-r-t:#991b1b;--tag-y:#fef9c3;--tag-y-t:#713f12;--tag-p:#f3e8ff;--tag-p-t:#581c87;\n --shadow:0 1px 3px rgba(0,0,.08);--radius:8px;--max-w:940px\n}\n[data-theme=\"dark\"]{\n --bg:#0b0b1a;--bg2:#16162a;--ink:#e2e4f0;--muted:#7f8396;--rule:#26263e;\n --accent:#60a5fa;--accent2:#4ade80;--accent3:#f87171;--accent4:#fbbf24;--accent5:#a78bfa;\n --card-bg:#16162a;--code-bg:#1e1e36;\n --tag-g:#14532d;--tag-g-t:#bbf7d0;--tag-b:#1e3a5f;--tag-b-t:#bfdbfe;\n --tag-r:#7f1d1d;--tag-r-t:#fecaca;--tag-y:#713f12;--tag-y-t:#fef08a;\n --tag-p:#3b1f6e;--tag-p-t:#e9d5ff;\n --shadow:0 1px 3px rgba(0,0,.3)\n}\nbody{font-family:-apple-system,BlinkMacSystemFont,\"Segoe UI\",\"Noto Sans SC\",\"PingFang SC\",\"Microsoft YaHei\",sans-serif;background:var(--bg);color:var(--ink);line-height:1.7;font-size:15px;transition:background .3s,color .3s}\nheader{position:fixed;top:0;left:0;right:0;z-index:100;background:var(--bg2);border-bottom:1px solid var(--rule);backdrop-filter:blur(12px);-webkit-backdrop-filter:blur(12px);transition:background .3s}\n.header-inner{max-width:var(--max-w);margin:0 auto;display:flex;align-items:center;justify-content:space-between;padding:0 1.5rem;height:56px}\n.logo{font-weight:700;font-size:.95rem;color:var(--accent);display:flex;align-items:center;gap:.4rem}\n.controls{display:flex;align-items:center;gap:.5rem}\n.lang-switch{display:flex;border:1px solid var(--rule);border-radius:6px;overflow:hidden}\n.lang-switch button{background:0 0;border:none;color:var(--muted);padding:.3rem .7rem;font-size:.8rem;cursor:pointer;transition:all .2s;font-family:inherit}\n.lang-switch button.active{background:var(--accent);color:#fff}\n.lang-switch button:not(.active):hover{color:var(--ink);background:var(--rule)}\n.theme-toggle{background:0 0;border:1px solid var(--rule);border-radius:6px;color:var(--muted);width:34px;height:34px;font-size:1rem;cursor:pointer;display:flex;align-items:center;transition:all .2s}\n.theme-toggle:hover{color:var(--ink);background:var(--rule)}\nmain{max-width:var(--max-w);margin:0 auto;padding:80px 1.5rem 3rem}\n.lang-section{display:none}.lang-section.active{display:block}\nh1{font-size:1.9rem;font-weight:800;line-height:1.3;margin-bottom:.5rem;letter-spacing:-.02em}\nh1 .sub{display:block;font-size:.85rem;font-weight:400;color:var(--muted);margin-top:.25rem;letter-spacing:0}\nh2{font-size:1.35rem;font-weight:700;margin:2.5rem 0 1rem;padding-bottom:.5rem;border-bottom:2px solid var(--accent);letter-spacing:-.01em}\nh3{font-size:1.05rem;font-weight:600;margin:1.5rem 0 .6rem;color:var(--accent)}\nh4{font-size:.95rem;font-weight:600;margin:1rem 0 .4rem;color:var(--ink)}\np{margin-bottom:.8rem}\na{color:var(--accent);text-decoration:none}a:hover{text-decoration:underline}\n.hero{text-align:center;padding:2rem 0 1rem}\n.hero p{font-size:1rem;color:var(--muted);max-width:700px;margin:0 auto}\n.tag{display:inline-block;padding:.12rem .5rem;border-radius:4px;font-size:.72rem;font-weight:600;margin-right:.25rem;white-space:nowrap}\n.tag-g{background:var(--tag-g);color:var(--tag-g-t)}.tag-b{background:var(--tag-b);color:var(--tag-b-t)}\n.tag-r{background:var(--tag-r);color:var(--tag-r-t)}.tag-y{background:var(--tag-y);color:var(--tag-y-t)}.tag-p{background:var(--tag-p);color:var(--tag-p-t)}\n.card{background:var(--card-bg);border:1px solid var(--rule);border-radius:var(--radius);padding:1.25rem;margin-bottom:1rem;box-shadow:var(--shadow)}\n.info-box{background:var(--bg);border-left:4px solid var(--accent);padding:.9rem 1.1rem;margin:1rem 0;border-radius:0 var(--radius) var(--radius) 0;font-size:.88rem}\n.info-box strong{color:var(--accent)}\n.info-box.warn{border-left-color:var(--accent4)}.info-box.warn strong{color:var(--accent4)}\n.info-box.danger{border-left-color:var(--accent3)}.info-box.danger strong{color:var(--accent3)}\n.toc{background:var(--card-bg);border:1px solid var(--rule);border-radius:var(--radius);padding:1.15rem 1.4rem;margin-bottom:2rem;box-shadow:var(--shadow)}\n.toc h3{margin:0 0 .5rem;font-size:.9rem;color:var(--muted);text-transform:uppercase;letter-spacing:.05em}\n.toc ol{padding-left:1.1rem;columns:2;column-gap:2rem}\n.toc li{margin-bottom:.25rem;font-size:.88rem}.toc a{color:var(--ink)}.toc a:hover{color:var(--accent);text-decoration:none}\npre.code-block{background:var(--code-bg);padding:.85rem 1rem;border-radius:var(--radius);overflow-x:auto;font-family:\"SF Mono\",Consolas,\"Courier New\",monospace;font-size:.82rem;line-height:1.5;margin:.6rem 0;border:1px solid var(--rule)}\ncode,.inline-code{background:var(--code-bg);padding:.12rem .4rem;border-radius:4px;font-family:\"SF Mono\",Consolas,\"Courier New\",monospace;font-size:.83rem;border:1px solid var(--rule)}\n.table-wrap{overflow-x:auto;margin:1.2rem 0}\ntable{width:100%;border-collapse:collapse;font-size:.82rem}\nthead th{background:var(--accent);color:#fff;padding:.6rem .5rem;text-align:center;font-weight:600;white-space:nowrap}\nthead th:first-child{border-radius:6px 0 0 0}thead th:last-child{border-radius:0 6px 0 0}\ntbody td{padding:.55rem .5rem;border-bottom:1px solid var(--rule);text-align:center;vertical-align:middle}\ntbody tr:nth-child(even){background:var(--bg)}\ntbody td:first-child{text-align:left;font-weight:600}\n.terminal{background:#1a1a2e;color:#a8e6cf;border-radius:var(--radius);padding:.9rem 1rem;font-family:\"SF Mono\",Consolas,\"Courier New\",monospace;font-size:.82rem;line-height:1.6;margin:.6rem 0;overflow-x:auto;border:1px solid #333}\n.terminal .prompt{color:#60a5fa}.terminal .comment{color:#6c7086;font-style:italic}.terminal .output{color:#e2e4f0}\n[data-theme=\"dark\"] .terminal{background:#08081a}\n.steps{counter-reset:step;list-style:none;padding:0}\n.steps li{counter-increment:step;position:relative;padding:.85rem 1rem .85rem 2.8rem;margin-bottom:.5rem;border-left:2px solid var(--rule);border-radius:0 var(--radius) 0;background:var(--card-bg);box-shadow:var(--shadow)}\n.steps li::before{content:counter(step);position:absolute;left:-13px;top:.85rem;width:26px;height:26px;border-radius:50%;background:var(--accent);color:#fff;display:flex;align-items:center;justify-content:center;font-size:.78rem;font-weight:700}\n.steps li .cmd{display:block;background:var(--code-bg);padding:.4rem .7rem;border-radius:5px;font-family:\"SF Mono\",Consolas,\"Courier New\",monospace;font-size:.82rem;margin:.3rem 0;overflow-x:auto;border:1px solid var(--rule)}\n.steps li .note{display:block;color:var(--muted);font-size:.82rem;margin-top:.2rem}\n.flow-diagram{background:var(--card-bg);border:1px solid var(--rule);border-radius:var(--radius);padding:1.25rem;margin:1.25rem 0;text-align:center}\n.flow-row{display:flex;align-items:center;justify-content:center;flex-wrap:wrap;gap:.35rem;margin:.4rem 0}\n.flow-item{display:inline-block;padding:.4rem .8rem;border-radius:6px;font-weight:600;font-size:.82rem;text-align:center;background:var(--accent);color:#fff;min-width:60px}\n.flow-item.green{background:var(--accent2)}.flow-item.red{background:var(--accent3)}.flow-item.yellow{background:var(--accent4);color:#1a1a2e}.flow-item.purple{background:var(--accent5)}\n.flow-arrow{color:var(--muted);font-size:1rem}\n.cmd-grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(280px,1fr));gap:.75rem;margin:1rem 0}\n.cmd-card{background:var(--card-bg);border:1px solid var(--rule);border-radius:var(--radius);padding:.9rem;box-shadow:var(--shadow)}\n.cmd-card h4{margin:0 0 .35rem;font-size:.88rem;color:var(--accent)}\n.cmd-card .cmd{font-family:\"SF Mono\",Consolas,\"Courier New\",monospace;font-size:.8rem;background:var(--code-bg);padding:.3rem .5rem;border-radius:4px;display:block;margin-bottom:.3rem;border:1px solid var(--rule)}\n.cmd-card .desc{font-size:.8rem;color:var(--muted)}\n.two-col{display:grid;grid-template-columns:1fr 1fr;gap:1.25rem;margin:1.25rem 0}\n.col{background:var(--card-bg);border:1px solid var(--rule);border-radius:var(--radius);padding:1.25rem;box-shadow:var(--shadow)}\n.col h4{margin-top:0}\n.compare-box{display:grid;grid-template-columns:1fr 1fr;gap:1rem;margin:1rem 0}\n.compare-col{background:var(--card-bg);border:1px solid var(--rule);border-radius:var(--radius);padding:1rem;box-shadow:var(--shadow)}\n.compare-col h4{margin:0 0 .4rem;font-size:.88rem}\n.compare-col.bad h4{color:var(--accent3)}\n.compare-col.good h4{color:var(--accent2)}\npre.example{background:var(--code-bg);padding:.6rem .8rem;border-radius:6px;font-family:\"SF Mono\",Consolas,\"Courier New\",monospace;font-size:.78rem;line-height:1.5;margin:.4rem 0;border:1px solid var(--rule);color:var(--ink)}\nfooter{max-width:var(--max-w);margin:3rem auto 0;padding:2rem 1.5rem 3rem;border-top:1px solid var(--rule);text-align:center;font-size:.82rem;color:var(--muted)}\nfooter .links{display:flex;justify-content:center;gap:1.5rem;flex-wrap:wrap;margin-bottom:.8rem}\nfooter .links a{color:var(--muted)}footer .links a:hover{color:var(--accent)}\n@media(max-width:640px){\n h1{font-size:1.4rem}.toc ol{columns:1}.header-inner{padding:0 1rem}main{padding:72px 1rem 2rem}\n .steps li{padding-left:2.4rem}.steps li::before{left:-11px;width:22px;height:22px;font-size:.7rem}\n .two-col{grid-template-columns:1fr}.cmd-grid{grid-template-columns:1fr}.compare-box{grid-template-columns:1fr}\n}\n<\/style>\n<\/head>\n<body>\n<header>\n <div class=\"header-inner\">\n <div class=\"logo\"><span>\u2699\ufe0f<\/span> \u9ed8\u8ba4\u503c\u7ba1\u7406\u5b8c\u6574\u6307\u5357<\/div>\n <div class=\"controls\">\n <div class=\"lang-switch\">\n <button class=\"active\" onclick=\"setLang('zh')\" id=\"btn-zh\">\u4e2d\u6587<\/button>\n <button onclick=\"setLang('en')\" id=\"btn-en\">English<\/button>\n <\/div>\n <button class=\"theme-toggle\" onclick=\"toggleTheme()\" title=\"\u5207\u6362\u660e\u6697\u4e3b\u9898\">☼<\/button>\n <\/div>\n <\/div>\n<\/header>\n<main>\n\n<div class=\"lang-section active\" id=\"lang-zh\">\n<div class=\"hero\">\n <h1>\u9ed8\u8ba4\u503c\u7ba1\u7406\u5b8c\u6574\u6307\u5357\uff08\u4e3a\u4f55\u9700\u8981\u2192\u5982\u4f55\u7edf\u4e00\u2192\u6700\u4f73\u5b9e\u8df5\uff09<span class=\"sub\">\u4ece\u7406\u89e3\u9ed8\u8ba4\u503c\u7684\u4ef7\u503c\u5230\u5efa\u7acb\u7edf\u4e00\u7684\u9ed8\u8ba4\u503c\u7ba1\u7406\u4f53\u7cfb<\/span><\/h1>\n <p>\u4e3a\u4ec0\u4e48\u9700\u8981\u9ed8\u8ba4\u503c\u3001\u9ed8\u8ba4\u503c\u7684\u5e94\u7528\u573a\u666f\u3001\u7edf\u4e00\u7ba1\u7406\u7b56\u7565\u3001\u914d\u7f6e\u6587\u4ef6\u8bbe\u8ba1\u3001\u4ee3\u7801\u5b9e\u73b0\u6a21\u5f0f\u3001\u73af\u5883\u5dee\u5f02\u5904\u7406\u3001\u5e38\u89c1\u95ee\u9898\u4e0e\u6700\u4f73\u5b9e\u8df5\u5168\u8986\u76d6<\/p>\n<\/div>\n\n<div class=\"toc\">\n <h3>\u76ee\u5f55<\/h3>\n <ol>\n <li><a href=\"#zh-1\">\u4e00\u3001\u4e3a\u4ec0\u4e48\u5f00\u53d1\u8fc7\u7a0b\u4e2d\u9700\u8981\u9ed8\u8ba4\u503c<\/a><\/li>\n <li><a href=\"#zh-2\">\u4e8c\u3001\u9ed8\u8ba4\u503c\u7684\u5e94\u7528\u573a\u666f\u5206\u7c7b<\/a><\/li>\n <li><a href=\"#zh-3\">\u4e09\u3001\u9ed8\u8ba4\u503c\u7684\u5e38\u89c1\u9677\u9631<\/a><\/li>\n <li><a href=\"#zh-4\">\u56db\u3001\u7edf\u4e00\u7ba1\u7406\u9ed8\u8ba4\u503c\u7684\u6838\u5fc3\u7b56\u7565<\/a><\/li>\n <li><a href=\"#zh-5\">\u4e94\u3001Python \u4e2d\u9ed8\u8ba4\u503c\u7ba1\u7406\u7684\u5b9e\u73b0\u6a21\u5f0f<\/a><\/li>\n <li><a href=\"#zh-6\">\u516d\u3001\u914d\u7f6e\u6587\u4ef6\u4e0e\u9ed8\u8ba4\u503c\u5206\u5c42\u8bbe\u8ba1<\/a><\/li>\n <li><a href=\"#zh-7\">\u4e03\u3001\u4e0d\u540c\u73af\u5883\u7684\u9ed8\u8ba4\u503c\u8986\u76d6<\/a><\/li>\n <li><a href=\"#zh-8\">\u516b\u3001\u9ed8\u8ba4\u503c\u53d8\u66f4\u4e0e\u7248\u672c\u7ba1\u7406<\/a><\/li>\n <li><a href=\"#zh-9\">\u4e5d\u3001\u9ed8\u8ba4\u503c\u4f7f\u7528\u6700\u4f73\u5b9e\u8df5<\/a><\/li>\n <li><a href=\"#zh-10\">\u5341\u3001\u5e38\u89c1\u95ee\u9898\u4e0e\u6392\u67e5<\/a><\/li>\n <\/ol>\n<\/div>\n\n\n<h2 id=\"zh-1\">\u4e00\u3001\u4e3a\u4ec0\u4e48\u5f00\u53d1\u8fc7\u7a0b\u4e2d\u9700\u8981\u9ed8\u8ba4\u503c<\/h2>\n\n<p>\u9ed8\u8ba4\u503c\uff08Default Value\uff09\u662f\u6307\u5728\u7528\u6237\u672a\u663e\u5f0f\u63d0\u4f9b\u67d0\u4e2a\u914d\u7f6e\u6216\u53c2\u6570\u65f6\uff0c\u7cfb\u7edf\u81ea\u52a8\u91c7\u7528\u7684\u9884\u8bbe\u503c\u3002\u5b83\u662f\u8fde\u63a5”\u7075\u6d3b\u914d\u7f6e”\u4e0e”\u5f00\u7bb1\u5373\u7528”\u7684\u5173\u952e\u6865\u6881\u3002<\/p>\n\n<div class=\"compare-box\">\n <div class=\"compare-col bad\">\n <h4>\u274c \u65e0\u9ed8\u8ba4\u503c\uff08\u5f3a\u5236\u914d\u7f6e\uff09<\/h4>\n<pre class=\"example\"># \u7528\u6237\u5fc5\u987b\u63d0\u4f9b\u6240\u6709\u53c2\u6570\nconnect_to_database(host=?, port=?, user=?, password=?,\n timeout=?, pool_size=?, charset=?)\n# \u542f\u52a8\u62a5\u9519\uff1a\u7f3a\u5c11\u5fc5\u586b\u53c2\u6570\n# \u6bcf\u4e2a\u65b0\u6210\u5458\u9700\u8981\u9605\u8bfb\u5927\u91cf\u6587\u6863\n# \u914d\u7f6e\u9879\u81a8\u80c0\uff0c50% \u7684\u53c2\u6570\u5927\u5bb6\u90fd\u7528\u540c\u4e00\u4e2a\u503c<\/pre>\n <p>\u4f7f\u7528\u95e8\u69db\u9ad8\u3001\u914d\u7f6e\u5197\u4f59\u3001\u542f\u52a8\u5931\u8d25\u7387\u9ad8\u3001\u65b0\u4eba\u4e0a\u624b\u6162\u3002<\/p>\n <\/div>\n <div class=\"compare-col good\">\n <h4>\u2705 \u5408\u7406\u9ed8\u8ba4\u503c\uff08\u4f18\u96c5\u964d\u7ea7\uff09<\/h4>\n<pre class=\"example\"># \u53ea\u9700\u63d0\u4f9b\u771f\u6b63\u4e2a\u6027\u5316\u7684\u53c2\u6570\nconnect_to_database(\n host=\"prod-db.internal\",\n password=os.getenv(\"DB_PASSWORD\")\n)\n# timeout=30, pool_size=10, charset=utf8mb4 \u81ea\u52a8\u751f\u6548\n# 90% \u7684\u573a\u666f\u65e0\u9700\u989d\u5916\u914d\u7f6e<\/pre>\n <p>\u964d\u4f4e\u4f7f\u7528\u95e8\u69db\u3001\u51cf\u5c11\u914d\u7f6e\u91cf\u3001\u63d0\u9ad8\u7a33\u5b9a\u6027\u3001\u52a0\u901f\u5f00\u53d1\u3002<\/p>\n <\/div>\n<\/div>\n\n<div class=\"card\">\n <h4>\u9ed8\u8ba4\u503c\u7684\u4e94\u5927\u6838\u5fc3\u4ef7\u503c<\/h4>\n <p><span class=\"tag tag-b\">\u964d\u4f4e\u95e8\u69db<\/span> \u65b0\u7528\u6237\u65e0\u9700\u4e86\u89e3\u6240\u6709\u7ec6\u8282\u5373\u53ef\u8fd0\u884c\uff0c\u5b9e\u73b0”\u5f00\u7bb1\u5373\u7528”<\/p>\n <p><span class=\"tag tag-g\">\u9632\u5fa1\u7f16\u7a0b<\/span> \u9632\u6b62\u56e0\u914d\u7f6e\u7f3a\u5931\u5bfc\u81f4\u7684\u8fd0\u884c\u65f6\u5f02\u5e38\uff0c\u63d0\u5347\u7cfb\u7edf\u9c81\u68d2\u6027<\/p>\n <p><span class=\"tag tag-y\">\u7edf\u4e00\u6807\u51c6<\/span> \u56e2\u961f\u5171\u4eab\u4e00\u5957\u7ecf\u8fc7\u9a8c\u8bc1\u7684\u57fa\u51c6\u914d\u7f6e\uff0c\u907f\u514d\u5404\u81ea\u4e3a\u653f<\/p>\n <p><span class=\"tag tag-p\">\u5411\u540e\u517c\u5bb9<\/span> \u65b0\u589e\u914d\u7f6e\u9879\u65f6\uff0c\u8001\u7528\u6237\u65e0\u9700\u4fee\u6539\u5373\u53ef\u5e73\u6ed1\u5347\u7ea7<\/p>\n <p><span class=\"tag tag-r\">\u5b89\u5168\u515c\u5e95<\/span> \u5173\u952e\u5b89\u5168\u53c2\u6570\uff08\u8d85\u65f6\u3001\u91cd\u8bd5\u6b21\u6570\uff09\u8bbe\u6709\u4fdd\u5b88\u9ed8\u8ba4\u503c\uff0c\u9632\u6b62\u8bef\u914d\u7f6e\u5bfc\u81f4\u4e8b\u6545<\/p>\n<\/div>\n\n<div class=\"info-box\">\n <strong>\u6838\u5fc3\u539f\u5219\uff1a\u9ed8\u8ba4\u503c\u4e0d\u662f”\u968f\u4fbf\u586b\u4e00\u4e2a\u503c”\uff0c\u800c\u662f\u7ecf\u8fc7\u56e2\u961f\u8bc4\u4f30\u3001\u751f\u4ea7\u9a8c\u8bc1\u3001\u6587\u6863\u8bf4\u660e\u7684”\u63a8\u8350\u914d\u7f6e”\u3002\u597d\u7684\u9ed8\u8ba4\u503c\u8ba9 80% \u7684\u7528\u6237\u65e0\u9700\u8c03\u6574\u5373\u53ef\u4f7f\u7528\uff0c20% \u7684\u9ad8\u7ea7\u7528\u6237\u53ef\u4ee5\u901a\u8fc7\u663e\u5f0f\u914d\u7f6e\u8986\u76d6\u3002<\/strong>\n<\/div>\n\n\n<h2 id=\"zh-2\">\u4e8c\u3001\u9ed8\u8ba4\u503c\u7684\u5e94\u7528\u573a\u666f\u5206\u7c7b<\/h2>\n\n<h3>2.1 \u6309\u4f5c\u7528\u57df\u5206\u7c7b<\/h3>\n<div class=\"table-wrap\">\n<table>\n <thead>\n <tr><th>\u4f5c\u7528\u57df<\/th><th>\u793a\u4f8b<\/th><th>\u7ba1\u7406\u65b9\u5f0f<\/th><\/tr>\n <\/thead>\n <tbody>\n <tr><td>\u8bed\u8a00\u7ea7\u9ed8\u8ba4<\/td><td>\u51fd\u6570\u53c2\u6570\u9ed8\u8ba4\u503c <code>def fn(x=10)<\/code><\/td><td>\u4ee3\u7801\u4e2d\u786c\u7f16\u7801<\/td><\/tr>\n <tr><td>\u6a21\u5757\u7ea7\u9ed8\u8ba4<\/td><td>\u6570\u636e\u5e93\u8fde\u63a5\u6c60\u5927\u5c0f\u3001HTTP \u8d85\u65f6\u65f6\u95f4<\/td><td>\u6a21\u5757\u5e38\u91cf\/\u914d\u7f6e\u7c7b<\/td><\/tr>\n <tr><td>\u9879\u76ee\u7ea7\u9ed8\u8ba4<\/td><td>\u670d\u52a1\u7aef\u53e3\u53f7\u3001\u65e5\u5fd7\u7ea7\u522b\u3001\u7ebf\u7a0b\u6570<\/td><td>\u914d\u7f6e\u6587\u4ef6\/\u73af\u5883\u53d8\u91cf<\/td><\/tr>\n <tr><td>\u73af\u5883\u7ea7\u9ed8\u8ba4<\/td><td>\u751f\u4ea7\/\u5f00\u53d1\u73af\u5883\u7684\u6570\u636e\u5e93\u5730\u5740<\/td><td>\u73af\u5883\u53d8\u91cf\/\u914d\u7f6e\u6587\u4ef6\u5206\u5c42<\/td><\/tr>\n <tr><td>\u7528\u6237\u7ea7\u9ed8\u8ba4<\/td><td>\u7528\u6237\u504f\u597d\u8bbe\u7f6e\u3001\u754c\u9762\u4e3b\u9898<\/td><td>\u7528\u6237\u914d\u7f6e\u6587\u4ef6\/\u6570\u636e\u5e93<\/td><\/tr>\n <\/tbody>\n<\/table>\n<\/div>\n\n<h3>2.2 \u6309\u7c7b\u578b\u5206\u7c7b<\/h3>\n<pre class=\"code-block\"># 1. \u51fd\u6570\/\u65b9\u6cd5\u53c2\u6570\u9ed8\u8ba4\u503c\ndef fetch_data(url: str, timeout: int = 30, retries: int = 3) -> dict:\n \"\"\"\u83b7\u53d6\u8fdc\u7a0b\u6570\u636e\uff0c\u8d85\u65f6\u9ed8\u8ba4 30 \u79d2\uff0c\u91cd\u8bd5\u9ed8\u8ba4 3 \u6b21\u3002\"\"\"\n\n# 2. \u7c7b\u5c5e\u6027\u9ed8\u8ba4\u503c\nclass DatabaseConfig:\n host: str = \"localhost\"\n port: int = 3306\n pool_size: int = 10\n charset: str = \"utf8mb4\"\n\n# 3. \u914d\u7f6e\u9879\u9ed8\u8ba4\u503c\nDEFAULT_CONFIG = {\n \"server\": {\"host\": \"0.0.0.0\", \"port\": 8000},\n \"database\": {\"timeout\": 30, \"pool_size\": 10},\n \"cache\": {\"ttl\": 3600, \"max_size\": 1000},\n \"logging\": {\"level\": \"INFO\", \"format\": \"standard\"},\n}\n\n# 4. \u73af\u5883\u53d8\u91cf\u9ed8\u8ba4\u503c\nDB_HOST = os.getenv(\"DB_HOST\", \"localhost\")\nDB_PORT = int(os.getenv(\"DB_PORT\", \"3306\"))\nDEBUG = os.getenv(\"DEBUG\", \"false\").lower() == \"true\"\n\n# 5. Pydantic \u6a21\u578b\u9ed8\u8ba4\u503c\nfrom pydantic import BaseModel, Field\n\nclass AppConfig(BaseModel):\n port: int = Field(default=8000, ge=1, le=65535)\n workers: int = Field(default=4, ge=1)\n timeout: float = Field(default=30.0, gt=0)\n<\/pre>\n\n\n<h2 id=\"zh-3\">\u4e09\u3001\u9ed8\u8ba4\u503c\u7684\u5e38\u89c1\u9677\u9631<\/h2>\n\n<h3>3.1 Python \u53ef\u53d8\u9ed8\u8ba4\u53c2\u6570\u9677\u9631<\/h3>\n<div class=\"compare-box\">\n <div class=\"compare-col bad\">\n <h4>\u274c \u9519\u8bef\u7684\u53ef\u53d8\u9ed8\u8ba4\u503c<\/h4>\n<pre class=\"example\">def append_item(item, items=[]):\n items.append(item)\n return items\n\nprint(append_item(1)) # [1]\nprint(append_item(2)) # [1, 2] \u2190 \u610f\u5916\uff01<\/pre>\n <p>\u5217\u8868\u5728\u51fd\u6570\u5b9a\u4e49\u65f6\u521b\u5efa\uff0c\u88ab\u591a\u6b21\u8c03\u7528\u5171\u4eab\uff0c\u5bfc\u81f4\u72b6\u6001\u6cc4\u6f0f\u3002<\/p>\n <\/div>\n <div class=\"compare-col good\">\n <h4>\u2705 \u6b63\u786e\u7684\u505a\u6cd5<\/h4>\n<pre class=\"example\">def append_item(item, items=None):\n if items is None:\n items = []\n items.append(item)\n return items\n\nprint(append_item(1)) # [1]\nprint(append_item(2)) # [2] \u2190 \u6b63\u786e<\/pre>\n <p>\u4f7f\u7528 None \u4f5c\u4e3a\u54e8\u5175\u503c\uff0c\u5728\u51fd\u6570\u4f53\u5185\u521b\u5efa\u65b0\u5bf9\u8c61\u3002<\/p>\n <\/div>\n<\/div>\n\n<h3>3.2 \u5176\u4ed6\u5e38\u89c1\u9677\u9631<\/h3>\n<div class=\"table-wrap\">\n<table>\n <thead>\n <tr><th>\u9677\u9631<\/th><th>\u73b0\u8c61<\/th><th>\u89e3\u51b3\u65b9\u6848<\/th><\/tr>\n <\/thead>\n <tbody>\n <tr>\n <td>\u9b54\u6cd5\u6570\u5b57\u6563\u843d<\/td>\n <td>\u4ee3\u7801\u5404\u5904\u51fa\u73b0 30\u30013600\u30011024 \u7b49\u6570\u5b57\uff0c\u542b\u4e49\u4e0d\u660e<\/td>\n <td>\u63d0\u53d6\u4e3a\u547d\u540d\u5e38\u91cf\uff0c\u5982 TIMEOUT_SECONDS = 30<\/td>\n <\/tr>\n <tr>\n <td>\u9ed8\u8ba4\u503c\u8fc7\u4e8e\u6fc0\u8fdb<\/td>\n <td>\u9ed8\u8ba4\u8fde\u63a5\u6c60 100\uff0c\u672c\u5730\u5f00\u53d1\u76f4\u63a5\u8017\u5c3d\u6570\u636e\u5e93\u8d44\u6e90<\/td>\n <td>\u9ed8\u8ba4\u503c\u504f\u4fdd\u5b88\uff0c\u6309\u73af\u5883\u63d0\u4f9b\u8986\u76d6\u65b9\u6848<\/td>\n <\/tr>\n <tr>\n <td>\u9ed8\u8ba4\u503c\u4e0e\u5b9e\u9645\u8131\u8282<\/td>\n <td>\u6587\u6863\u5199\u9ed8\u8ba4 30 \u79d2\uff0c\u4ee3\u7801\u91cc\u662f 60 \u79d2<\/td>\n <td>\u5355\u4e00\u6570\u636e\u6e90\uff0c\u4ee3\u7801\u4e0e\u6587\u6863\u81ea\u52a8\u751f\u6210<\/td>\n <\/tr>\n <tr>\n <td>\u9ed8\u8ba4\u503c\u672a\u6587\u6863\u5316<\/td>\n <td>\u7528\u6237\u4e0d\u77e5\u9053\u67d0\u4e2a\u53c2\u6570\u7684\u9ed8\u8ba4\u503c\u662f\u4ec0\u4e48<\/td>\n <td>\u5728\u51fd\u6570\u7b7e\u540d\u3001\u914d\u7f6e\u6587\u4ef6\u6a21\u677f\u4e2d\u663e\u5f0f\u6807\u6ce8<\/td>\n <\/tr>\n <tr>\n <td>\u5e03\u5c14\u9ed8\u8ba4\u503c\u6b67\u4e49<\/td>\n <td><code>flag=True<\/code> \u8bed\u4e49\u4e0d\u6e05\uff0c\u4e0d\u77e5\u9053\u4ee3\u8868\u4ec0\u4e48<\/td>\n <td>\u4f7f\u7528\u5177\u540d\u53c2\u6570\u6216\u679a\u4e3e\uff0c\u5982 <code>mode=Mode.AUTO<\/code><\/td>\n <\/tr>\n <\/tbody>\n<\/table>\n<\/div>\n\n\n<h2 id=\"zh-4\">\u56db\u3001\u7edf\u4e00\u7ba1\u7406\u9ed8\u8ba4\u503c\u7684\u6838\u5fc3\u7b56\u7565<\/h2>\n\n<h3>4.1 \u5355\u4e00\u6570\u636e\u6e90\u539f\u5219\uff08Single Source of Truth\uff09<\/h3>\n<div class=\"flow-diagram\">\n <div class=\"flow-row\">\n <span class=\"flow-item green\">defaults.py<\/span>\n <span class=\"flow-arrow\">←<\/span>\n <span class=\"flow-item\">\u552f\u4e00\u9ed8\u8ba4\u503c\u5b9a\u4e49<\/span>\n <span class=\"flow-arrow\">→<\/span>\n <span class=\"flow-item yellow\">\u914d\u7f6e\u6587\u4ef6<\/span>\n <span class=\"flow-arrow\">→<\/span>\n <span class=\"flow-item purple\">\u73af\u5883\u53d8\u91cf<\/span>\n <span class=\"flow-arrow\">→<\/span>\n <span class=\"flow-item\">\u8fd0\u884c\u65f6\u8986\u76d6<\/span>\n <\/div>\n<\/div>\n\n<div class=\"info-box\">\n <strong>\u4f18\u5148\u7ea7\u89c4\u5219\uff1a\u8fd0\u884c\u65f6\u4f20\u5165 > \u73af\u5883\u53d8\u91cf > \u914d\u7f6e\u6587\u4ef6 > \u4ee3\u7801\u9ed8\u8ba4\u503c\u3002\u4efb\u4f55\u5c42\u7ea7\u7684\u914d\u7f6e\u90fd\u5e94\u5f53\u4ee5\u4ee3\u7801\u4e2d\u7684\u9ed8\u8ba4\u503c\u4e3a\u6700\u7ec8\u515c\u5e95\u3002<\/strong>\n<\/div>\n\n<h3>4.2 \u63a8\u8350\u7684\u5c42\u7ea7\u8986\u76d6\u67b6\u6784<\/h3>\n<pre class=\"code-block\">\u914d\u7f6e\u52a0\u8f7d\u4f18\u5148\u7ea7\uff08\u4ece\u9ad8\u5230\u4f4e\uff09\uff1a\n\n1. \u547d\u4ee4\u884c\u53c2\u6570\uff08\u6700\u4f18\u5148\uff0c\u4e34\u65f6\u8c03\u8bd5\uff09\n python main.py --port 9000 --debug\n\n2. \u73af\u5883\u53d8\u91cf\uff08CI\/CD \u90e8\u7f72\u65f6\u6ce8\u5165\uff09\n export APP_PORT=9000\n export APP_DEBUG=true\n\n3. \u672c\u5730\u914d\u7f6e\u6587\u4ef6\uff08\u5f00\u53d1\u73af\u5883\u4e2a\u6027\u5316\uff09\n config\/dev.yaml\n\n4. \u9879\u76ee\u9ed8\u8ba4\u914d\u7f6e\uff08\u4ed3\u5e93\u4e2d\u63d0\u4ea4\u7684\u57fa\u7840\u503c\uff09\n config\/default.yaml\n\n5. \u4ee3\u7801\u786c\u7f16\u7801\u9ed8\u8ba4\u503c\uff08\u6700\u7ec8\u515c\u5e95\uff09\n PORT: int = 8000\n<\/pre>\n\n\n<h2 id=\"zh-5\">\u4e94\u3001Python \u4e2d\u9ed8\u8ba4\u503c\u7ba1\u7406\u7684\u5b9e\u73b0\u6a21\u5f0f<\/h2>\n\n<h3>5.1 \u6a21\u5f0f\u4e00\uff1a\u5e38\u91cf\u6a21\u5757<\/h3>\n<pre class=\"code-block\"># src\/myapp\/defaults.py\n\"\"\"\u9879\u76ee\u6240\u6709\u9ed8\u8ba4\u503c\u7684\u5355\u4e00\u6570\u636e\u6e90\u3002\"\"\"\n\nfrom pathlib import Path\n\n# \u670d\u52a1\u5668\nDEFAULT_HOST: str = \"0.0.0.0\"\nDEFAULT_PORT: int = 8000\nDEFAULT_WORKERS: int = 4\nDEFAULT_TIMEOUT: float = 30.0\n\n# \u6570\u636e\u5e93\nDEFAULT_DB_HOST: str = \"localhost\"\nDEFAULT_DB_PORT: int = 3306\nDEFAULT_DB_POOL_SIZE: int = 10\nDEFAULT_DB_CHARSET: str = \"utf8mb4\"\n\n# \u7f13\u5b58\nDEFAULT_CACHE_TTL: int = 3600\nDEFAULT_CACHE_MAX_SIZE: int = 1000\n\n# \u65e5\u5fd7\nDEFAULT_LOG_LEVEL: str = \"INFO\"\nDEFAULT_LOG_FORMAT: str = \"standard\"\nDEFAULT_LOG_FILE: Path = Path(\"logs\/app.log\")\n\n# \u5176\u4ed6\nMAX_UPLOAD_SIZE: int = 10 * 1024 * 1024 # 10MB\nREQUEST_RETRY_COUNT: int = 3\nREQUEST_RETRY_BACKOFF: float = 1.5\n<\/pre>\n\n<h3>5.2 \u6a21\u5f0f\u4e8c\uff1aPydantic Settings\uff08\u63a8\u8350\uff09<\/h3>\n<pre class=\"code-block\"># src\/myapp\/config.py\nfrom pydantic import Field\nfrom pydantic_settings import BaseSettings, SettingsConfigDict\n\n\nclass DatabaseConfig(BaseSettings):\n \"\"\"\u6570\u636e\u5e93\u914d\u7f6e\uff0c\u652f\u6301\u73af\u5883\u53d8\u91cf\u8986\u76d6\u3002\"\"\"\n model_config = SettingsConfigDict(env_prefix=\"DB_\")\n\n host: str = Field(default=\"localhost\", description=\"\u6570\u636e\u5e93\u5730\u5740\")\n port: int = Field(default=3306, ge=1, le=65535)\n user: str = Field(default=\"root\")\n password: str = Field(default=\"\")\n pool_size: int = Field(default=10, ge=1, le=100)\n timeout: float = Field(default=30.0, gt=0)\n charset: str = Field(default=\"utf8mb4\")\n\n\nclass AppConfig(BaseSettings):\n \"\"\"\u5e94\u7528\u5168\u5c40\u914d\u7f6e\u3002\"\"\"\n model_config = SettingsConfigDict(\n env_file=\".env\",\n env_file_encoding=\"utf-8\",\n extra=\"ignore\"\n )\n\n env: str = Field(default=\"dev\", pattern=\"^(dev|test|staging|prod)$\")\n host: str = Field(default=\"0.0.0.0\")\n port: int = Field(default=8000, ge=1, le=65535)\n workers: int = Field(default=4, ge=1)\n debug: bool = Field(default=False)\n\n database: DatabaseConfig = Field(default_factory=DatabaseConfig)\n\n log_level: str = Field(default=\"INFO\")\n log_format: str = Field(default=\"standard\")\n\n\n# \u4f7f\u7528\nconfig = AppConfig()\nprint(config.port) # 8000\uff08\u9ed8\u8ba4\u503c\uff09\nprint(config.database.host) # localhost\uff08\u9ed8\u8ba4\u503c\uff09\n# \u73af\u5883\u53d8\u91cf DB_HOST=prod-db \u65f6\uff0cconfig.database.host = \"prod-db\"\n<\/pre>\n\n<h3>5.3 \u6a21\u5f0f\u4e09\uff1adataclasses + \u5408\u5e76<\/h3>\n<pre class=\"code-block\">from dataclasses import dataclass, field, asdict\nfrom typing import Optional\nimport os\n\n\n@dataclass\nclass ServerConfig:\n host: str = \"0.0.0.0\"\n port: int = 8000\n workers: int = 4\n\n\n@dataclass\nclass AppConfig:\n env: str = \"dev\"\n debug: bool = False\n server: ServerConfig = field(default_factory=ServerConfig)\n\n @classmethod\n def from_env(cls) -> \"AppConfig\":\n \"\"\"\u4ece\u73af\u5883\u53d8\u91cf\u52a0\u8f7d\uff0c\u8986\u76d6\u9ed8\u8ba4\u503c\u3002\"\"\"\n cfg = cls()\n if \"APP_PORT\" in os.environ:\n cfg.server.port = int(os.environ[\"APP_PORT\"])\n if \"APP_DEBUG\" in os.environ:\n cfg.debug = os.environ[\"APP_DEBUG\"].lower() == \"true\"\n return cfg\n\n def merge(self, overrides: dict) -> \"AppConfig\":\n \"\"\"\u5408\u5e76\u5b57\u5178\u8986\u76d6\u5230\u5f53\u524d\u914d\u7f6e\u3002\"\"\"\n data = asdict(self)\n data.update(overrides)\n return self.__class__(**data)\n<\/pre>\n\n\n<h2 id=\"zh-6\">\u516d\u3001\u914d\u7f6e\u6587\u4ef6\u4e0e\u9ed8\u8ba4\u503c\u5206\u5c42\u8bbe\u8ba1<\/h2>\n\n<h3>6.1 \u63a8\u8350\u9879\u76ee\u7ed3\u6784<\/h3>\n<pre class=\"code-block\">config\/\n\u251c\u2500\u2500 default.yaml # \u6240\u6709\u9ed8\u8ba4\u503c\uff0c\u63d0\u4ea4\u5230 Git\n\u251c\u2500\u2500 default.yaml.example # \u5e26\u8bf4\u660e\u7684\u6a21\u677f\uff08\u65b0\u4eba\u53c2\u8003\uff09\n\u251c\u2500\u2500 dev.yaml # \u5f00\u53d1\u73af\u5883\u8986\u76d6\uff08\u53ef\u9009\uff0c\u4e0d\u63d0\u4ea4 Git\uff09\n\u251c\u2500\u2500 test.yaml # \u6d4b\u8bd5\u73af\u5883\u8986\u76d6\n\u2514\u2500\u2500 prod.yaml # \u751f\u4ea7\u73af\u5883\u8986\u76d6\uff08CI\/CD \u6ce8\u5165\uff09\n<\/pre>\n\n<h3>6.2 default.yaml \u8bbe\u8ba1<\/h3>\n<pre class=\"code-block\"># config\/default.yaml\n# \u6240\u6709\u914d\u7f6e\u9879\u5fc5\u987b\u6709\u9ed8\u8ba4\u503c\uff0c\u6ce8\u91ca\u8bf4\u660e\u7528\u9014\u548c\u5355\u4f4d\n\nserver:\n host: \"0.0.0.0\" # \u76d1\u542c\u5730\u5740\uff0c0.0.0.0 \u8868\u793a\u6240\u6709\u63a5\u53e3\n port: 8000 # \u670d\u52a1\u7aef\u53e3\n workers: 4 # \u5de5\u4f5c\u8fdb\u7a0b\u6570\uff0cCPU \u6838\u5fc3\u6570\u7684 2 \u500d\u4e3a\u5b9c\n timeout: 30.0 # \u8bf7\u6c42\u8d85\u65f6\u65f6\u95f4\uff08\u79d2\uff09\n\ndatabase:\n host: \"localhost\" # \u6570\u636e\u5e93\u5730\u5740\n port: 3306 # \u6570\u636e\u5e93\u7aef\u53e3\n pool_size: 10 # \u8fde\u63a5\u6c60\u5927\u5c0f\n timeout: 30.0 # \u8fde\u63a5\u8d85\u65f6\uff08\u79d2\uff09\n charset: \"utf8mb4\" # \u6570\u636e\u5e93\u5b57\u7b26\u96c6\n\ncache:\n enabled: true # \u662f\u5426\u542f\u7528\u7f13\u5b58\n ttl: 3600 # \u7f13\u5b58\u8fc7\u671f\u65f6\u95f4\uff08\u79d2\uff09\n max_size: 1000 # \u6700\u5927\u7f13\u5b58\u6761\u76ee\u6570\n\nlogging:\n level: \"INFO\" # \u65e5\u5fd7\u7ea7\u522b\uff1aDEBUG\/INFO\/WARNING\/ERROR\n format: \"standard\" # \u65e5\u5fd7\u683c\u5f0f\uff1astandard\/json\n file: \"logs\/app.log\" # \u65e5\u5fd7\u6587\u4ef6\u8def\u5f84\n\nsecurity:\n max_upload_size: 10485760 # \u6700\u5927\u4e0a\u4f20\u6587\u4ef6\u5927\u5c0f\uff08\u5b57\u8282\uff0c\u9ed8\u8ba4 10MB\uff09\n password_min_length: 8 # \u5bc6\u7801\u6700\u5c0f\u957f\u5ea6\n session_ttl: 86400 # Session \u8fc7\u671f\u65f6\u95f4\uff08\u79d2\uff0c\u9ed8\u8ba4 1 \u5929\uff09\n\nretry:\n count: 3 # \u8bf7\u6c42\u5931\u8d25\u91cd\u8bd5\u6b21\u6570\n backoff: 1.5 # \u9000\u907f\u4e58\u6570\n max_delay: 60.0 # \u6700\u5927\u91cd\u8bd5\u5ef6\u8fdf\uff08\u79d2\uff09\n<\/pre>\n\n<h3>6.3 \u914d\u7f6e\u52a0\u8f7d\u4e0e\u5408\u5e76<\/h3>\n<pre class=\"code-block\">import yaml\nfrom pathlib import Path\nfrom typing import Any\nimport os\n\n\ndef load_config(env: str | None = None) -> dict[str, Any]:\n \"\"\"\u52a0\u8f7d\u914d\u7f6e\uff0c\u6309\u4f18\u5148\u7ea7\u5408\u5e76\u3002\"\"\"\n config_dir = Path(\"config\")\n\n # 1. \u52a0\u8f7d\u9ed8\u8ba4\u503c\n default_path = config_dir \/ \"default.yaml\"\n config = yaml.safe_load(default_path.read_text(encoding=\"utf-8\"))\n\n # 2. \u52a0\u8f7d\u73af\u5883\u7279\u5b9a\u914d\u7f6e\uff08\u5982\u5b58\u5728\uff09\n env = env or os.getenv(\"APP_ENV\", \"dev\")\n env_path = config_dir \/ f\"{env}.yaml\"\n if env_path.exists():\n env_config = yaml.safe_load(env_path.read_text(encoding=\"utf-8\"))\n config = deep_merge(config, env_config)\n\n return config\n\n\ndef deep_merge(base: dict, override: dict) -> dict:\n \"\"\"\u6df1\u5ea6\u5408\u5e76\u4e24\u4e2a\u5b57\u5178\uff0coverride \u4f18\u5148\u3002\"\"\"\n result = base.copy()\n for key, value in override.items():\n if key in result and isinstance(result[key], dict) and isinstance(value, dict):\n result[key] = deep_merge(result[key], value)\n else:\n result[key] = value\n return result\n<\/pre>\n\n\n<h2 id=\"zh-7\">\u4e03\u3001\u4e0d\u540c\u73af\u5883\u7684\u9ed8\u8ba4\u503c\u8986\u76d6<\/h2>\n\n<h3>7.1 \u73af\u5883\u914d\u7f6e\u5dee\u5f02\u8868<\/h3>\n<div class=\"table-wrap\">\n<table>\n <thead>\n <tr><th>\u914d\u7f6e\u9879<\/th><th>default.yaml<\/th><th>dev.yaml<\/th><th>test.yaml<\/th><th>prod.yaml<\/th><\/tr>\n <\/thead>\n <tbody>\n <tr><td>debug<\/td><td>false<\/td><td>true<\/td><td>false<\/td><td>false<\/td><\/tr>\n <tr><td>server.workers<\/td><td>4<\/td><td>1<\/td><td>2<\/td><td>8<\/td><\/tr>\n <tr><td>database.host<\/td><td>localhost<\/td><td>localhost<\/td><td>test-db<\/td><td>prod-db.internal<\/td><\/tr>\n <tr><td>database.pool_size<\/td><td>10<\/td><td>5<\/td><td>5<\/td><td>50<\/td><\/tr>\n <tr><td>log.level<\/td><td>INFO<\/td><td>DEBUG<\/td><td>DEBUG<\/td><td>INFO<\/td><\/tr>\n <tr><td>cache.enabled<\/td><td>true<\/td><td>false<\/td><td>false<\/td><td>true<\/td><\/tr>\n <tr><td>retry.count<\/td><td>3<\/td><td>1<\/td><td>0<\/td><td>5<\/td><\/tr>\n <\/tbody>\n<\/table>\n<\/div>\n\n<h3>7.2 \u73af\u5883\u7279\u5b9a\u914d\u7f6e\u793a\u4f8b<\/h3>\n<pre class=\"code-block\"># config\/dev.yaml\n# \u5f00\u53d1\u73af\u5883\uff1a\u8c03\u8bd5\u53cb\u597d\uff0c\u6027\u80fd\u6b21\u8981\n\nserver:\n workers: 1 # \u5355\u8fdb\u7a0b\uff0c\u65b9\u4fbf\u65ad\u70b9\u8c03\u8bd5\n reload: true # \u4ee3\u7801\u53d8\u66f4\u81ea\u52a8\u91cd\u542f\n\ndatabase:\n pool_size: 5 # \u672c\u5730\u6570\u636e\u5e93\u538b\u529b\u5c0f\n echo: true # \u6253\u5370 SQL \u8bed\u53e5\n\nlogging:\n level: \"DEBUG\" # \u5f00\u53d1\u9700\u8981\u8be6\u7ec6\u65e5\u5fd7\n\ncache:\n enabled: false # \u5f00\u53d1\u65f6\u907f\u514d\u7f13\u5b58\u5e72\u6270\u8c03\u8bd5\n\n# config\/prod.yaml\n# \u751f\u4ea7\u73af\u5883\uff1a\u6027\u80fd\u4f18\u5148\uff0c\u5b89\u5168\u4fdd\u5b88\n\nserver:\n workers: 8 # \u591a\u8fdb\u7a0b\u5904\u7406\u5e76\u53d1\n reload: false # \u7981\u6b62\u81ea\u52a8\u91cd\u542f\n\ndatabase:\n pool_size: 50 # \u652f\u6491\u9ad8\u5e76\u53d1\n echo: false # \u5173\u95ed SQL \u6253\u5370\n\nlogging:\n level: \"INFO\" # \u51cf\u5c11\u65e5\u5fd7\u91cf\n\ncache:\n enabled: true # \u542f\u7528\u7f13\u5b58\u63d0\u5347\u6027\u80fd\n\nretry:\n count: 5 # \u7f51\u7edc\u4e0d\u7a33\u5b9a\u65f6\u66f4\u591a\u91cd\u8bd5\n<\/pre>\n\n\n<h2 id=\"zh-8\">\u516b\u3001\u9ed8\u8ba4\u503c\u53d8\u66f4\u4e0e\u7248\u672c\u7ba1\u7406<\/h2>\n\n<h3>8.1 \u9ed8\u8ba4\u503c\u53d8\u66f4\u7684\u5f71\u54cd<\/h3>\n<div class=\"info-box warn\">\n <strong>\u4fee\u6539\u9ed8\u8ba4\u503c\u662f\u6f5c\u5728\u7684\u7834\u574f\u6027\u53d8\u66f4\uff08Breaking Change\uff09\u3002\u5373\u4f7f\u4ee3\u7801\u6ca1\u6539\uff0c\u884c\u4e3a\u53ef\u80fd\u5df2\u53d8\u3002\u53d8\u66f4\u9ed8\u8ba4\u503c\u5fc5\u987b\u9075\u5faa\u7248\u672c\u7ba1\u7406\u89c4\u8303\u3002<\/strong>\n<\/div>\n\n<h3>8.2 \u53d8\u66f4\u89c4\u8303<\/h3>\n<div class=\"card\">\n <h4>\u9ed8\u8ba4\u503c\u53d8\u66f4\u4e09\u6761\u89c4\u5219<\/h4>\n <p>1. <span class=\"tag tag-r\">\u6587\u6863\u5148\u884c<\/span> \u4fee\u6539\u9ed8\u8ba4\u503c\u524d\uff0c\u5728 CHANGELOG \u4e2d\u8bf4\u660e\u53d8\u66f4\u539f\u56e0\u548c\u5f71\u54cd\u8303\u56f4<\/p>\n <p>2. <span class=\"tag tag-b\">\u7248\u672c\u6807\u8bb0<\/span> \u9ed8\u8ba4\u503c\u53d8\u66f4\u968f\u529f\u80fd\u53d1\u5e03\uff0c\u8bed\u4e49\u5316\u7248\u672c\uff1a\u529f\u80fd\u65b0\u589e\u7528 MINOR\uff0c\u9ed8\u8ba4\u503c\u5927\u5e45\u53d8\u66f4\u9700\u8bc4\u4f30\u662f\u5426 MAJOR<\/p>\n <p>3. <span class=\"tag tag-g\">\u517c\u5bb9\u6027\u8fc7\u6e21<\/span> \u91cd\u8981\u9ed8\u8ba4\u503c\u53d8\u66f4\u63d0\u4f9b\u8fc7\u6e21\u671f\uff1a\u65e7\u503c\u5e9f\u5f03\u8b66\u544a\uff0c\u4e0b\u4e00\u7248\u672c\u518d\u5207\u6362<\/p>\n<\/div>\n\n<pre class=\"code-block\"># \u8fc7\u6e21\u671f\u517c\u5bb9\u793a\u4f8b\nimport warnings\n\ndef connect_to_database(timeout: float | None = None) -> Connection:\n \"\"\"\u8fde\u63a5\u6570\u636e\u5e93\u3002\n\n Args:\n timeout: \u8fde\u63a5\u8d85\u65f6\uff08\u79d2\uff09\u3002\u9ed8\u8ba4 30 \u79d2\u3002\n \u6ce8\uff1a\u65e7\u9ed8\u8ba4\u503c 60 \u79d2\u5c06\u5728 v2.0 \u79fb\u9664\u3002\n \"\"\"\n if timeout is None:\n timeout = 30.0 # \u65b0\u9ed8\u8ba4\u503c\n elif timeout == 60.0:\n warnings.warn(\n \"\u9ed8\u8ba4\u8d85\u65f6\u5df2\u4ece 60 \u79d2\u6539\u4e3a 30 \u79d2\uff0c\"\n \"\u663e\u5f0f\u4f20\u5165 timeout=60 \u4ee5\u4fdd\u6301\u65e7\u884c\u4e3a\u3002\",\n DeprecationWarning,\n stacklevel=2\n )\n return _create_connection(timeout)\n<\/pre>\n\n\n<h2 id=\"zh-9\">\u4e5d\u3001\u9ed8\u8ba4\u503c\u4f7f\u7528\u6700\u4f73\u5b9e\u8df5<\/h2>\n\n<h3>9.1 \u6700\u4f73\u5b9e\u8df5\u6e05\u5355<\/h3>\n<div class=\"card\">\n <h4>\u8bbe\u8ba1\u4e0e\u5b9e\u73b0\u89c4\u8303<\/h4>\n <p>\u2705 <strong>\u5355\u4e00\u6570\u636e\u6e90<\/strong> \u6240\u6709\u9ed8\u8ba4\u503c\u96c6\u4e2d\u5728\u4e00\u4e2a\u6587\u4ef6\uff08defaults.py \u6216 default.yaml\uff09\uff0c\u7981\u6b62\u6563\u843d\u5728\u5404\u5904<\/p>\n <p>\u2705 <strong>\u547d\u540d\u5e38\u91cf<\/strong> \u7528\u6709\u610f\u4e49\u7684\u540d\u79f0\u66ff\u4ee3\u9b54\u6cd5\u6570\u5b57\uff0c\u5982 <code>DEFAULT_TIMEOUT = 30<\/code> \u800c\u975e <code>30<\/code><\/p>\n <p>\u2705 <strong>\u7c7b\u578b\u6ce8\u89e3<\/strong> \u4e3a\u6240\u6709\u9ed8\u8ba4\u503c\u6dfb\u52a0\u7c7b\u578b\u6ce8\u89e3\uff0c\u4fbf\u4e8e\u9759\u6001\u68c0\u67e5\u548c IDE \u63d0\u793a<\/p>\n <p>\u2705 <strong>\u5355\u4f4d\u6807\u6ce8<\/strong> \u65f6\u95f4\/\u5927\u5c0f\u7c7b\u9ed8\u8ba4\u503c\u5728\u6ce8\u91ca\u4e2d\u6ce8\u660e\u5355\u4f4d\uff08\u79d2\u3001\u5b57\u8282\u3001\u6beb\u79d2\uff09<\/p>\n <p>\u2705 <strong>\u8303\u56f4\u6821\u9a8c<\/strong> \u5bf9\u6570\u503c\u578b\u9ed8\u8ba4\u503c\u8bbe\u7f6e\u5408\u7406\u7684\u4e0a\u4e0b\u754c\uff08Pydantic Field \u7684 ge\/le\uff09<\/p>\n <p>\u2705 <strong>\u73af\u5883\u9694\u79bb<\/strong> \u4e0d\u540c\u73af\u5883\u7684\u8986\u76d6\u914d\u7f6e\u5355\u72ec\u5b58\u653e\uff0cdefault \u504f\u4fdd\u5b88\uff0c\u751f\u4ea7\u6309\u9700\u653e\u5927<\/p>\n <p>\u2705 <strong>\u5411\u540e\u517c\u5bb9<\/strong> \u65b0\u589e\u914d\u7f6e\u9879\u5fc5\u987b\u6709\u9ed8\u8ba4\u503c\uff0c\u786e\u4fdd\u8001\u7528\u6237\u65e0\u9700\u4fee\u6539\u5373\u53ef\u5347\u7ea7<\/p>\n <p>\u2705 <strong>\u5b9a\u671f\u5ba1\u8ba1<\/strong> \u6bcf\u5b63\u5ea6 Review \u9ed8\u8ba4\u503c\u662f\u5426\u4ecd\u7b26\u5408\u5f53\u524d\u7cfb\u7edf\u89c4\u6a21\u548c\u6700\u4f73\u5b9e\u8df5<\/p>\n<\/div>\n\n<h3>9.2 \u9ed8\u8ba4\u503c Review Checklist<\/h3>\n<pre class=\"code-block\"># \u4ee3\u7801 Review \u65f6\u68c0\u67e5\u9ed8\u8ba4\u503c\n\u25a1 \u9ed8\u8ba4\u503c\u662f\u5426\u6765\u81ea defaults.py\uff08\u800c\u975e\u9b54\u6cd5\u6570\u5b57\uff09\n\u25a1 \u9ed8\u8ba4\u503c\u662f\u5426\u7ecf\u8fc7\u751f\u4ea7\u9a8c\u8bc1\uff08\u800c\u975e\u62cd\u8111\u888b\uff09\n\u25a1 \u5e03\u5c14\u9ed8\u8ba4\u503c\u8bed\u4e49\u662f\u5426\u6e05\u6670\uff08\u662f\u5426\u9700\u8981\u679a\u4e3e\u66ff\u4ee3\uff09\n\u25a1 \u65f6\u95f4\/\u5927\u5c0f\u7c7b\u662f\u5426\u6709\u5355\u4f4d\u6ce8\u91ca\n\u25a1 \u53ef\u53d8\u5bf9\u8c61\u662f\u5426\u4f7f\u7528\u4e86 None \u54e8\u5175\uff08\u907f\u514d\u5171\u4eab\u72b6\u6001\uff09\n\u25a1 \u65b0\u589e\u914d\u7f6e\u9879\u662f\u5426\u6709\u9ed8\u8ba4\u503c\uff08\u5411\u540e\u517c\u5bb9\uff09\n\u25a1 \u9ed8\u8ba4\u503c\u53d8\u66f4\u662f\u5426\u5728 CHANGELOG \u4e2d\u8bb0\u5f55\n\u25a1 \u654f\u611f\u914d\u7f6e\uff08\u5bc6\u7801\u3001\u5bc6\u94a5\uff09\u662f\u5426\u6ca1\u6709\u9ed8\u8ba4\u503c\uff08\u5f3a\u5236\u7528\u6237\u586b\u5199\uff09\n<\/pre>\n\n\n<h2 id=\"zh-10\">\u5341\u3001\u5e38\u89c1\u95ee\u9898\u4e0e\u6392\u67e5<\/h2>\n\n<div class=\"table-wrap\">\n<table>\n <thead>\n <tr><th>\u95ee\u9898\u73b0\u8c61<\/th><th>\u539f\u56e0<\/th><th>\u89e3\u51b3\u65b9\u6848<\/th><\/tr>\n <\/thead>\n <tbody>\n <tr>\n <td>\u9ed8\u8ba4\u503c\u672a\u751f\u6548<\/td>\n <td>\u52a0\u8f7d\u987a\u5e8f\u9519\u8bef\uff0c\u73af\u5883\u53d8\u91cf\u6216\u914d\u7f6e\u6587\u4ef6\u8986\u76d6\u4e86\u9ed8\u8ba4\u503c\u4f46\u672a\u6ce8\u610f<\/td>\n <td>\u6253\u5370\u6700\u7ec8\u914d\u7f6e\uff0c\u786e\u8ba4\u5404\u5c42\u7ea7\u52a0\u8f7d\u7ed3\u679c\uff1b\u4f7f\u7528 Pydantic Settings \u81ea\u52a8\u8ffd\u8e2a<\/td>\n <\/tr>\n <tr>\n <td>\u4e0d\u540c\u673a\u5668\u884c\u4e3a\u4e0d\u4e00\u81f4<\/td>\n <td>\u672c\u5730\u6709\u672a\u63d0\u4ea4\u7684 dev.yaml\uff0c\u5176\u4ed6\u4eba\u6ca1\u6709<\/td>\n <td>.gitignore \u6392\u9664\u672c\u5730\u8986\u76d6\u6587\u4ef6\uff0c\u56e2\u961f\u5171\u4eab\u914d\u7f6e\u901a\u8fc7\u73af\u5883\u53d8\u91cf\u6216\u7edf\u4e00\u914d\u7f6e\u4e2d\u5fc3<\/td>\n <\/tr>\n <tr>\n <td>\u9ed8\u8ba4\u503c\u53d8\u66f4\u5bfc\u81f4\u7ebf\u4e0a\u6545\u969c<\/td>\n <td>\u5347\u7ea7\u7248\u672c\u65f6\u672a\u6ce8\u610f\u5230\u9ed8\u8ba4\u503c\u5df2\u4fee\u6539<\/td>\n <td>CHANGELOG \u9192\u76ee\u6807\u6ce8 Breaking Changes\uff1b\u5347\u7ea7\u524d diff \u914d\u7f6e\u53d8\u66f4<\/td>\n <\/tr>\n <tr>\n <td>\u914d\u7f6e\u9879\u592a\u591a\u96be\u4ee5\u7ba1\u7406<\/td>\n <td>\u7f3a\u4e4f\u5206\u5c42\uff0c\u6240\u6709\u914d\u7f6e\u5e73\u94fa\u5728\u4e00\u4e2a\u6587\u4ef6<\/td>\n <td>\u6309\u6a21\u5757\u5206\u7ec4\uff08server\/database\/cache\/logging\uff09\uff0c\u5fc5\u8981\u65f6\u62c6\u5206\u5b50\u914d\u7f6e\u7c7b<\/td>\n <\/tr>\n <tr>\n <td>\u5bc6\u7801\u7b49\u6709\u9ed8\u8ba4\u503c\u5bfc\u81f4\u5b89\u5168\u98ce\u9669<\/td>\n <td>\u654f\u611f\u914d\u7f6e\u8bbe\u7f6e\u4e86\u9ed8\u8ba4\u503c\uff0c\u7528\u6237\u672a\u8986\u76d6<\/td>\n <td>\u654f\u611f\u914d\u7f6e\u4e0d\u8bbe\u9ed8\u8ba4\u503c\uff0c\u542f\u52a8\u65f6\u5f3a\u5236\u6821\u9a8c\u7f3a\u5931\u5373\u62a5\u9519<\/td>\n <\/tr>\n <tr>\n <td>\u9ed8\u8ba4\u503c\u7c7b\u578b\u9519\u8bef<\/td>\n <td>\u73af\u5883\u53d8\u91cf\u90fd\u662f\u5b57\u7b26\u4e32\uff0c\u672a\u6b63\u786e\u8f6c\u6362<\/td>\n <td>\u4f7f\u7528 Pydantic \u81ea\u52a8\u8f6c\u6362\uff0c\u6216\u663e\u5f0f int()\/float()\/bool() \u8f6c\u6362<\/td>\n <\/tr>\n <\/tbody>\n<\/table>\n<\/div>\n\n<h3>\u5feb\u901f\u6392\u67e5\u547d\u4ee4<\/h3>\n<pre class=\"terminal\"><span class=\"comment\"># \u67e5\u770b\u5f53\u524d\u751f\u6548\u7684\u6240\u6709\u914d\u7f6e<\/span>\n<span class=\"prompt\">python -c<\/span> \"from myapp.config import config; print(config.model_dump_json(indent=2))\"\n\n<span class=\"comment\"># \u67e5\u770b\u67d0\u4e2a\u914d\u7f6e\u7684\u6765\u6e90<\/span>\n<span class=\"prompt\">python -c<\/span> \"from myapp.config import config; print(config.port)\n<span class=\"output\">8000<\/span>\n\n<span class=\"comment\"># \u68c0\u67e5\u73af\u5883\u53d8\u91cf\u662f\u5426\u8986\u76d6<\/span>\n<span class=\"prompt\">$env:APP_PORT<\/span>\n<span class=\"output\">9000 # \u73af\u5883\u53d8\u91cf\u8986\u76d6\u4e86\u9ed8\u8ba4\u503c<\/span>\n<\/pre>\n\n<div class=\"info-box\">\n <strong>\u5168\u6d41\u7a0b\u603b\u7ed3\uff1a\u7406\u89e3\u9ed8\u8ba4\u503c\u964d\u4f4e\u95e8\u69db\u548c\u9632\u5fa1\u7f16\u7a0b\u7684\u4ef7\u503c \u2192 \u5c06\u9ed8\u8ba4\u503c\u96c6\u4e2d\u7ba1\u7406\uff08\u5355\u4e00\u6570\u636e\u6e90\uff09\u2192 \u4f7f\u7528 Pydantic\/dataclasses \u5b9e\u73b0\u7c7b\u578b\u5b89\u5168 \u2192 \u914d\u7f6e\u6587\u4ef6\u5206\u5c42\uff08default + env-specific\uff09\u2192 \u73af\u5883\u53d8\u91cf\u53ef\u8986\u76d6 \u2192 \u53d8\u66f4\u65f6\u6587\u6863\u5316\u5e76\u8003\u8651\u517c\u5bb9\u6027 \u2192 \u5b9a\u671f\u5ba1\u8ba1\u9ed8\u8ba4\u503c\u5408\u7406\u6027\u3002\u597d\u7684\u9ed8\u8ba4\u503c\u8ba9\u7cfb\u7edf\u65e2\u7075\u6d3b\u53c8\u7a33\u5065\u3002<\/strong>\n<\/div>\n\n<\/div>\n\n\n<div class=\"lang-section\" id=\"lang-en\">\n<div class=\"hero\">\n <h1>Default Values Management Complete Guide<span class=\"sub\">Why We Need Them & How to Manage Them Systematically<\/span><\/h1>\n <p>Why defaults matter, application scenarios, common pitfalls, unified management strategies, Python implementation patterns, config layering, environment overrides, versioning & best practices<\/p>\n<\/div>\n\n<div class=\"toc\">\n <h3>Table of Contents<\/h3>\n <ol>\n <li><a href=\"#en-1\">1 Why We Need Default Values<\/a><\/li>\n <li><a href=\"#en-2\">2 Application Scenarios<\/a><\/li>\n <li><a href=\"#en-3\">3 Common Pitfalls<\/a><\/li>\n <li><a href=\"#en-4\">4 Unified Management Strategy<\/a><\/li>\n <li><a href=\"#en-5\">5 Python Implementation Patterns<\/a><\/li>\n <li><a href=\"#en-6\">6 Config File Layering<\/a><\/li>\n <li><a href=\"#en-7\">7 Environment-Specific Overrides<\/a><\/li>\n <li><a href=\"#en-8\">8 Changing Defaults & Versioning<\/a><\/li>\n <li><a href=\"#en-9\">9 Best Practices<\/a><\/li>\n <li><a href=\"#en-10\">10 FAQ & Troubleshooting<\/a><\/li>\n <\/ol>\n<\/div>\n\n<h2 id=\"en-1\">1 Why We Need Default Values<\/h2>\n\n<div class=\"card\">\n <h4>Five Core Values<\/h4>\n <p><span class=\"tag tag-b\">Lower Barrier<\/span> New users can run without learning all details<\/p>\n <p><span class=\"tag tag-g\">Defensive Coding<\/span> Prevent runtime errors from missing config<\/p>\n <p><span class=\"tag tag-y\">Unified Standards<\/span> Team shares validated baseline configurations<\/p>\n <p><span class=\"tag tag-p\">Backward Compatible<\/span> Existing users upgrade smoothly without changes<\/p>\n <p><span class=\"tag tag-r\">Safety Net<\/span> Conservative defaults for timeouts, retries prevent incidents<\/p>\n<\/div>\n\n<div class=\"info-box\">\n <strong>Core Principle: Default values are not “random guesses” but “team-vetted, production-tested recommendations.” Good defaults let 80% of users run without tuning, while 20% power users can override explicitly.<\/strong>\n<\/div>\n\n<h2 id=\"en-2\">2 Application Scenarios<\/h2>\n\n<div class=\"table-wrap\">\n<table>\n <thead><tr><th>Scope<\/th><th>Example<\/th><th>Management<\/th><\/tr><\/thead>\n <tbody>\n <tr><td>Language-level<\/td><td>Function params <code>def fn(x=10)<\/code><\/td><td>Hard-coded<\/td><\/tr>\n <tr><td>Module-level<\/td><td>DB pool size, HTTP timeout<\/td><td>Module constants<\/td><\/tr>\n <tr><td>Project-level<\/td><td>Server port, log level<\/td><td>Config file \/ env vars<\/td><\/tr>\n <tr><td>Environment-level<\/td><td>Prod vs dev DB host<\/td><td>Env vars \/ layered config<\/td><\/tr>\n <tr><td>User-level<\/td><td>Preferences, theme<\/td><td>User config \/ database<\/td><\/tr>\n <\/tbody>\n<\/table>\n<\/div>\n\n<h2 id=\"en-3\">3 Common Pitfalls<\/h2>\n\n<h3>Mutable Default Argument Trap<\/h3>\n<div class=\"compare-box\">\n <div class=\"compare-col bad\">\n <h4>\u274c Wrong<\/h4>\n<pre class=\"example\">def append_item(item, items=[]):\n items.append(item)\n return items\n\nprint(append_item(1)) # [1]\nprint(append_item(2)) # [1, 2] \u2190 surprise!<\/pre>\n <\/div>\n <div class=\"compare-col good\">\n <h4>\u2705 Correct<\/h4>\n<pre class=\"example\">def append_item(item, items=None):\n if items is None:\n items = []\n items.append(item)\n return items<\/pre>\n <\/div>\n<\/div>\n\n<h2 id=\"en-4\">4 Unified Management Strategy<\/h2>\n\n<div class=\"flow-diagram\">\n <div class=\"flow-row\">\n <span class=\"flow-item green\">defaults.py<\/span>\n <span class=\"flow-arrow\">←<\/span>\n <span class=\"flow-item\">Single Source of Truth<\/span>\n <span class=\"flow-arrow\">→<\/span>\n <span class=\"flow-item yellow\">Config File<\/span>\n <span class=\"flow-arrow\">→<\/span>\n <span class=\"flow-item purple\">Env Vars<\/span>\n <span class=\"flow-arrow\">→<\/span>\n <span class=\"flow-item\">Runtime Override<\/span>\n <\/div>\n<\/div>\n\n<div class=\"info-box\">\n <strong>Priority: Runtime args > Env vars > Config file > Code defaults. Every layer falls back to code defaults.<\/strong>\n<\/div>\n\n<h2 id=\"en-5\">5 Python Implementation Patterns<\/h2>\n\n<h3>Pattern 1: Constants Module<\/h3>\n<pre class=\"code-block\"># defaults.py\nDEFAULT_HOST: str = \"0.0.0.0\"\nDEFAULT_PORT: int = 8000\nDEFAULT_TIMEOUT: float = 30.0\nDEFAULT_DB_POOL_SIZE: int = 10\n<\/pre>\n\n<h3>Pattern 2: Pydantic Settings (Recommended)<\/h3>\n<pre class=\"code-block\">from pydantic import Field\nfrom pydantic_settings import BaseSettings, SettingsConfigDict\n\nclass AppConfig(BaseSettings):\n model_config = SettingsConfigDict(env_file=\".env\")\n port: int = Field(default=8000, ge=1, le=65535)\n workers: int = Field(default=4, ge=1)\n timeout: float = Field(default=30.0, gt=0)\n\nconfig = AppConfig() # Auto loads from env vars\n<\/pre>\n\n<h3>Pattern 3: dataclasses + Merge<\/h3>\n<pre class=\"code-block\">from dataclasses import dataclass, field\n\n@dataclass\nclass AppConfig:\n env: str = \"dev\"\n debug: bool = False\n server_port: int = 8000\n\n @classmethod\n def from_env(cls) -> \"AppConfig\":\n cfg = cls()\n if \"APP_PORT\" in os.environ:\n cfg.server_port = int(os.environ[\"APP_PORT\"])\n return cfg\n<\/pre>\n\n<h2 id=\"en-6\">6 Config File Layering<\/h2>\n\n<pre class=\"code-block\">config\/\n\u251c\u2500\u2500 default.yaml # All defaults, committed to Git\n\u251c\u2500\u2500 default.yaml.example # Template with explanations\n\u251c\u2500\u2500 dev.yaml # Dev overrides (optional, .gitignore)\n\u251c\u2500\u2500 test.yaml # Test overrides\n\u2514\u2500\u2500 prod.yaml # Production overrides (CI\/CD injected)\n<\/pre>\n\n<h3>Loading & Merging<\/h3>\n<pre class=\"code-block\">def load_config(env: str | None = None) -> dict:\n config = yaml.safe_load(Path(\"config\/default.yaml\").read_text())\n env = env or os.getenv(\"APP_ENV\", \"dev\")\n env_path = Path(f\"config\/{env}.yaml\")\n if env_path.exists():\n env_config = yaml.safe_load(env_path.read_text())\n config = deep_merge(config, env_config)\n return config\n<\/pre>\n\n<h2 id=\"en-7\">7 Environment-Specific Overrides<\/h2>\n\n<div class=\"table-wrap\">\n<table>\n <thead><tr><th>Setting<\/th><th>default<\/th><th>dev<\/th><th>test<\/th><th>prod<\/th><\/tr><\/thead>\n <tbody>\n <tr><td>debug<\/td><td>false<\/td><td>true<\/td><td>false<\/td><td>false<\/td><\/tr>\n <tr><td>workers<\/td><td>4<\/td><td>1<\/td><td>2<\/td><td>8<\/td><\/tr>\n <tr><td>db.pool_size<\/td><td>10<\/td><td>5<\/td><td>5<\/td><td>50<\/td><\/tr>\n <tr><td>log.level<\/td><td>INFO<\/td><td>DEBUG<\/td><td>DEBUG<\/td><td>INFO<\/td><\/tr>\n <tr><td>cache.enabled<\/td><td>true<\/td><td>false<\/td><td>false<\/td><td>true<\/td><\/tr>\n <\/tbody>\n<\/table>\n<\/div>\n\n<h2 id=\"en-8\">8 Changing Defaults & Versioning<\/h2>\n\n<div class=\"info-box warn\">\n <strong>Changing a default is a potential Breaking Change. Even if code doesn’t change, behavior might. Follow versioning rules.<\/strong>\n<\/div>\n\n<div class=\"card\">\n <h4>Three Rules for Changing Defaults<\/h4>\n <p>1. <span class=\"tag tag-r\">Document First<\/span> Update CHANGELOG before changing<\/p>\n <p>2. <span class=\"tag tag-b\">Version Tag<\/span> Follow semver: minor for additions, major for breaking default changes<\/p>\n <p>3. <span class=\"tag tag-g\">Transition Period<\/span> Deprecate old value with warnings, switch in next version<\/p>\n<\/div>\n\n<h2 id=\"en-9\">9 Best Practices<\/h2>\n\n<div class=\"card\">\n <h4>Best Practices Checklist<\/h4>\n <p>\u2705 <strong>Single Source<\/strong> Centralize all defaults in one file<\/p>\n <p>\u2705 <strong>Named Constants<\/strong> Use <code>DEFAULT_TIMEOUT = 30<\/code> not magic numbers<\/p>\n <p>\u2705 <strong>Type Annotations<\/strong> Annotate all defaults for static checking<\/p>\n <p>\u2705 <strong>Unit Comments<\/strong> Document units (seconds, bytes, ms)<\/p>\n <p>\u2705 <strong>Bounds Check<\/strong> Set min\/max for numeric defaults<\/p>\n <p>\u2705 <strong>Environment Isolation<\/strong> Separate override configs per environment<\/p>\n <p>\u2705 <strong>Backward Compatible<\/strong> New config items must have defaults<\/p>\n <p>\u2705 <strong>Periodic Audit<\/strong> Review defaults quarterly<\/p>\n<\/div>\n\n<h2 id=\"en-10\">10 FAQ & Troubleshooting<\/h2>\n\n<div class=\"table-wrap\">\n<table>\n <thead><tr><th>Issue<\/th><th>Solution<\/th><\/tr><\/thead>\n <tbody>\n <tr><td>Default not applied<\/td><td>Check loading order; print final config to verify<\/td><\/tr>\n <tr><td>Inconsistent behavior across machines<\/td><td>.gitignore local override files; use env vars for team sharing<\/td><\/tr>\n <tr><td>Default change caused incident<\/td><td>Highlight breaking changes in CHANGELOG; diff configs before upgrade<\/td><\/tr>\n <tr><td>Too many configs to manage<\/td><td>Group by module (server\/db\/cache\/logging); use sub-config classes<\/td><\/tr>\n <tr><td>Security risk from default passwords<\/td><td>Never set defaults for secrets; fail on startup if missing<\/td><\/tr>\n <tr><td>Default type mismatch<\/td><td>Use Pydantic for auto-conversion, or explicit int()\/bool()<\/td><\/tr>\n <\/tbody>\n<\/table>\n<\/div>\n\n<div class=\"info-box\">\n <strong>Summary: Understand defaults lower barriers and provide safety nets \u2192 Centralize management (single source of truth) \u2192 Use Pydantic\/dataclasses for type safety \u2192 Layer configs (default + env-specific) \u2192 Allow env var overrides \u2192 Document changes with compatibility consideration \u2192 Audit defaults periodically. Good defaults make systems both flexible and robust.<\/strong>\n<\/div>\n\n<\/div>\n<\/main>\n\n<footer>\n <div class=\"links\">\n <a href=\"https:\/\/docs.pydantic.dev\/latest\/concepts\/pydantic_settings\/\" target=\"_blank\" rel=\"noopener\">Pydantic Settings<\/a>\n <a href=\"https:\/\/12factor.net\/config\" target=\"_blank\" rel=\"noopener\">12-Factor Config<\/a>\n <a href=\"https:\/\/docs.python.org\/3\/library\/argparse.html\" target=\"_blank\" rel=\"noopener\">argparse Docs<\/a>\n <\/div>\n <p>Default Values Management Complete Guide<\/p>\n<\/footer>\n\n<script>\nfunction setLang(lang){\n document.querySelectorAll('.lang-section').forEach(el=>el.classList.remove('active'));\n document.getElementById('lang-'+lang).classList.add('active');\n document.querySelectorAll('.lang-switch button').forEach(btn=>btn.classList.remove('active'));\n document.getElementById('btn-'+lang).classList.add('active');\n document.documentElement.lang = lang==='zh'?'zh-CN':'en';\n const prefix = lang==='zh'?'zh':'en';\n const newHash = window.location.hash.replace(\/^#(zh|en)-\/, prefix+\"-\");\n if(newHash) window.location.hash = newHash;\n}\nfunction toggleTheme(){\n const html = document.documentElement;\n if(html.hasAttribute('data-theme')){\n html.removeAttribute('data-theme');\n localStorage.removeItem('theme');\n }else{\n html.setAttribute('data-theme','dark');\n localStorage.setItem('theme','dark');\n }\n}\n(function(){\n if(localStorage.getItem('theme')==='dark') document.documentElement.setAttribute('data-theme','dark');\n const hash = window.location.hash;\n if(hash){\n const target = document.querySelector(hash);\n if(target) setTimeout(()=>target.scrollIntoView({behavior:'smooth'}),100);\n }\n})();\n<\/script>\n<\/body>\n<\/html>\n","protected":false},"excerpt":{"rendered":"<p>\u9ed8\u8ba4\u503c\u7ba1\u7406\u5b8c\u6574\u6307\u5357 \u00b7 Default Values Management Guide \u2699\ufe0f \u9ed8\u8ba4\u503c\u7ba1\u7406\u5b8c\u6574\u6307 […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[11,9],"tags":[],"class_list":["post-361","post","type-post","status-publish","format-standard","hentry","category-cad","category-ai"],"blocksy_meta":[],"_links":{"self":[{"href":"https:\/\/numsimlab.com\/index.php?rest_route=\/wp\/v2\/posts\/361","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/numsimlab.com\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/numsimlab.com\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/numsimlab.com\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/numsimlab.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=361"}],"version-history":[{"count":1,"href":"https:\/\/numsimlab.com\/index.php?rest_route=\/wp\/v2\/posts\/361\/revisions"}],"predecessor-version":[{"id":362,"href":"https:\/\/numsimlab.com\/index.php?rest_route=\/wp\/v2\/posts\/361\/revisions\/362"}],"wp:attachment":[{"href":"https:\/\/numsimlab.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=361"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/numsimlab.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=361"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/numsimlab.com\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=361"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}