python-gino.org/docs/zh/master/tutorials/fastapi.html at master · python-gino/python-gino.org

History

674 lines (609 loc) · 72.7 KB

Raw

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

323

324

325

326

327

328

329

330

331

332

333

334

335

336

337

338

339

340

341

342

343

344

345

346

347

348

349

350

351

352

353

354

355

356

357

358

359

360

361

362

363

364

365

366

367

368

369

370

371

372

373

374

375

376

377

378

379

380

381

382

383

384

385

386

387

388

389

390

391

392

393

394

395

396

397

398

399

400

401

402

403

404

405

406

407

408

409

410

411

412

413

414

415

416

417

418

419

420

421

422

423

424

425

426

427

428

429

430

431

432

433

434

435

436

437

438

439

440

441

442

443

444

445

446

447

448

449

450

451

452

453

454

455

456

457

458

459

460

461

462

463

464

465

466

467

468

469

470

471

472

473

474

475

476

477

478

479

480

481

482

483

484

485

486

487

488

489

490

491

492

493

494

495

496

497

498

499

500

501

502

503

504

505

506

507

508

509

510

511

512

513

514

515

516

517

518

519

520

521

522

523

524

525

526

527

528

529

530

531

532

533

534

535

536

537

538

539

540

541

542

543

544

545

546

547

548

549

550

551

552

553

554

555

556

557

558

559

560

561

562

563

564

565

566

567

568

569

570

571

572

573

574

575

576

577

578

579

580

581

582

583

584

585

586

587

588

589

590

591

592

593

594

595

596

597

598

599

600

601

602

603

604

605

606

607

608

609

610

611

612

613

614

615

616

617

618

619

620

621

622

623

624

625

626

627

628

629

630

631

632

633

634

635

636

637

638

639

640

641

642

643

644

645

646

647

648

649

650

651

652

653

654

655

656

657

658

659

660

661

662

663

664

665

666

667

668

669

670

671

672

673

674

<!DOCTYPE html>

<head>

<title>搭建一个 FastAPI 服务器 - GINO 1.1.0rc1 文档</title>

<script async

src="https://www.googletagmanager.com/gtag/js?id=UA-3759436-10"></script>

window.dataLayer = window.dataLayer || [];

function gtag () {

dataLayer.push(arguments);

}

gtag('js', new Date());

gtag('config', 'UA-3759436-10');

</script>

href="https://fonts.googleapis.com/css?family=Raleway:400,500,600,700&display=swap">

href="https://cdn.jsdelivr.net/npm/@mdi/font@latest/css/materialdesignicons.min.css">

href="../_static/css/materialize.min.css"

media="screen,projection"/>

type="text/css"/>

href="../_static/css/gino.css"/>

</head>

<body>

<nav>

<div class="img"

style="background-image: url(../_static/logo.svg); width: 103px; height: 40px;"></div>

</a>

<a href="../tutorials.html"

class="breadcrumb">上手教程</a>

<a class="breadcrumb" style="color: #FFFFFF">搭建一个 FastAPI 服务器</a>

</div>

</div>

首页

</a>

鸣谢

</a>

<a href="https://github.com/python-gino/gino" target="_blank"

class="github-stars">

<div class="left"><img

src="data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHN2ZyB3aWR0aD0iNDNweCIgaGVpZ2h0PSI0MnB4IiB2aWV3Qm94PSIwIDAgNDMgNDIiIHZlcnNpb249IjEuMSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayI+CiAgICA8IS0tIEdlbmVyYXRvcjogU2tldGNoIDYxLjIgKDg5NjUzKSAtIGh0dHBzOi8vc2tldGNoLmNvbSAtLT4KICAgIDx0aXRsZT5GaWxsIDQ5PC90aXRsZT4KICAgIDxkZXNjPkNyZWF0ZWQgd2l0aCBTa2V0Y2guPC9kZXNjPgogICAgPGcgaWQ9IlYzLeacgOaWsOeov+S7tiIgc3Ryb2tlPSJub25lIiBzdHJva2Utd2lkdGg9IjEiIGZpbGw9Im5vbmUiIGZpbGwtcnVsZT0iZXZlbm9kZCI+CiAgICAgICAgPGcgaWQ9IkhPTUUtdjMiIHRyYW5zZm9ybT0idHJhbnNsYXRlKC0xNTA3LjAwMDAwMCwgLTQ5LjAwMDAwMCkiIGZpbGw9IiNGRkZGRkUiPgogICAgICAgICAgICA8ZyBpZD0iYmFubmVyLWJnIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgtMzc5LjAwMDAwMCwgLTE4Ny4wMDAwMDApIj4KICAgICAgICAgICAgICAgIDxnIGlkPSJoZWFkZXIiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDU5Ny4wMDAwMDAsIDIxOC4wMDAwMDApIj4KICAgICAgICAgICAgICAgICAgICA8cGF0aCBkPSJNMTMxMC40OTgwMiwxOCBDMTI5OC42MjcxMiwxOCAxMjg5LDI3LjYzOTg4MzEgMTI4OSwzOS41MzIxMTIzIEMxMjg5LDQ5LjA0NTEwMjYgMTI5NS4xNTk4Myw1Ny4xMTQ2ODggMTMwMy43MDMzNCw1OS45NjE4NDM5IEMxMzA0Ljc3OTAzLDYwLjE2MDExMzggMTMwNS4xNzEwMyw1OS40OTUyNDg3IDEzMDUuMTcxMDMsNTguOTI0MjMxMyBDMTMwNS4xNzEwMyw1OC40MTI2OTUgMTMwNS4xNTI1NSw1Ny4wNTkxNzI0IDEzMDUuMTQxOTksNTUuMjYyODQ3IEMxMjk5LjE2MTY3LDU2LjU2MzQ5NzYgMTI5Ny44OTk4Nyw1Mi4zNzYwMzcxIDEyOTcuODk5ODcsNTIuMzc2MDM3MSBDMTI5Ni45MjE4NSw0OS44ODg0MTA2IDEyOTUuNTEyMjMsNDkuMjI2MTg5MSAxMjk1LjUxMjIzLDQ5LjIyNjE4OTEgQzEyOTMuNTYwMTUsNDcuODkxMTcxNyAxMjk1LjY2MDA2LDQ3LjkxNzYwNzcgMTI5NS42NjAwNiw0Ny45MTc2MDc3IEMxMjk3LjgxODA0LDQ4LjA2OTYxNDYgMTI5OC45NTMxMyw1MC4xMzY5MDg5IDEyOTguOTUzMTMsNTAuMTM2OTA4OSBDMTMwMC44NzA5LDUzLjQyNjg2NzYgMTMwMy45ODU3OSw1Mi40NzY0OTM4IDEzMDUuMjEwNjMsNTEuOTI1MzAzNSBDMTMwNS40MDU5Nyw1MC41MzQ3NzA1IDEzMDUuOTYxNjMsNDkuNTg1NzE4NiAxMzA2LjU3NTM3LDQ5LjA0Nzc0NjIgQzEzMDEuODAxNDEsNDguNTA0NDg2NiAxMjk2Ljc4MTk1LDQ2LjY1NjYxMTEgMTI5Ni43ODE5NSwzOC40MDU5MzkyIEMxMjk2Ljc4MTk1LDM2LjA1NTc3OTkgMTI5Ny42MjAwNiwzNC4xMzI1NjE3IDEyOTguOTk1MzcsMzIuNjI4MzU0IEMxMjk4Ljc3MzYzLDMyLjA4Mzc3MjYgMTI5OC4wMzU4MiwyOS44OTM1NTEgMTI5OS4yMDY1NCwyNi45MzAwNzY4IEMxMjk5LjIwNjU0LDI2LjkzMDA3NjggMTMwMS4wMTA4LDI2LjM1MTEyODYgMTMwNS4xMTgyNCwyOS4xMzc0ODE4IEMxMzA2LjgzMjc1LDI4LjY1ODk5MDQgMTMwOC42NzI2NCwyOC40MjEwNjY1IDEzMTAuNTAwNjYsMjguNDExODEzOSBDMTMxMi4zMjczNiwyOC40MjEwNjY1IDEzMTQuMTY1OTQsMjguNjU4OTkwNCAxMzE1Ljg4MzA4LDI5LjEzNzQ4MTggQzEzMTkuOTg3ODgsMjYuMzUxMTI4NiAxMzIxLjc4OTUsMjYuOTMwMDc2OCAxMzIxLjc4OTUsMjYuOTMwMDc2OCBDMTMyMi45NjI4NiwyOS44OTM1NTEgMTMyMi4yMjUwNSwzMi4wODM3NzI2IDEzMjIuMDA0NjMsMzIuNjI4MzU0IEMxMzIzLjM4MjU4LDM0LjEzMjU2MTcgMTMyNC4yMTQwOSwzNi4wNTU3Nzk5IDEzMjQuMjE0MDksMzguNDA1OTM5MiBDMTMyNC4yMTQwOSw0Ni42Nzc3NTk5IDEzMTkuMTg2NzIsNDguNDk3ODc3NiAxMzE0LjM5ODIzLDQ5LjAzMDU2MjggQzEzMTUuMTY5MDQsNDkuNjk1NDI3OSAxMzE1Ljg1NjY5LDUxLjAwOTI5NjUgMTMxNS44NTY2OSw1My4wMTcxMDk4IEMxMzE1Ljg1NjY5LDU1Ljg5NTk4ODkgMTMxNS44MzAyOSw1OC4yMTgzOTA1IDEzMTUuODMwMjksNTguOTI0MjMxMyBDMTMxNS44MzAyOSw1OS41MDA1MzU5IDEzMTYuMjE4MzMsNjAuMTcwNjg4MiAxMzE3LjMwODU0LDU5Ljk2MDUyMjEgQzEzMjUuODQ1NDUsNTcuMTA2NzU3MiAxMzMyLDQ5LjA0MjQ1OSAxMzMyLDM5LjUzMjExMjMgQzEzMzIsMjcuNjM5ODgzMSAxMzIyLjM3Mjg4LDE4IDEzMTAuNDk4MDIsMTgiIGlkPSJGaWxsLTQ5Ij48L3BhdGg+CiAgICAgICAgICAgICAgICA8L2c+CiAgICAgICAgICAgIDwvZz4KICAgICAgICA8L2c+CiAgICA8L2c+Cjwvc3ZnPg=="

class="github-logo">

GitHub

</div>

<div class="right"><img

src="data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHN2ZyB3aWR0aD0iMjFweCIgaGVpZ2h0PSIxOXB4IiB2aWV3Qm94PSIwIDAgMjEgMTkiIHZlcnNpb249IjEuMSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayI+CiAgICA8IS0tIEdlbmVyYXRvcjogU2tldGNoIDYxLjIgKDg5NjUzKSAtIGh0dHBzOi8vc2tldGNoLmNvbSAtLT4KICAgIDx0aXRsZT5QYXRoPC90aXRsZT4KICAgIDxkZXNjPkNyZWF0ZWQgd2l0aCBTa2V0Y2guPC9kZXNjPgogICAgPGcgaWQ9IlYzLeacgOaWsOeov+S7tiIgc3Ryb2tlPSJub25lIiBzdHJva2Utd2lkdGg9IjEiIGZpbGw9Im5vbmUiIGZpbGwtcnVsZT0iZXZlbm9kZCI+CiAgICAgICAgPGcgaWQ9IkhPTUUtdjMiIHRyYW5zZm9ybT0idHJhbnNsYXRlKC0xNTYxLjAwMDAwMCwgLTYwLjAwMDAwMCkiIGZpbGw9IiNGOEQyMzAiPgogICAgICAgICAgICA8ZyBpZD0iYmFubmVyLWJnIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgtMzc5LjAwMDAwMCwgLTE4Ny4wMDAwMDApIj4KICAgICAgICAgICAgICAgIDxnIGlkPSJoZWFkZXIiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDU5Ny4wMDAwMDAsIDIxOC4wMDAwMDApIj4KICAgICAgICAgICAgICAgICAgICA8ZyBpZD0ibGFiZWwtY29weS0xMiIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMTI4OS4wMDAwMDAsIDE4LjAwMDAwMCkiPgogICAgICAgICAgICAgICAgICAgICAgICA8cG9seWdvbiBpZD0iUGF0aCIgcG9pbnRzPSI2MS4wNTQzNTQzIDE3Ljc1NzM4MzYgNTQuMjE1MjQ2NiAxOC4zMTMzOTI5IDU5Ljg4OTM1MTcgMjIuOTczNzM4NyA1Ny43ODQ1MjI4IDI5Ljg0MDExODQgNjQuNDQyNTI3MSAyNi41NDM0MTg4IDcwLjU3NzcyMzkgMjkuODQwMTE4NCA2OS4yMzA0MzI1IDIyLjk3MzczODcgNzQuNzMyNTY5NiAxOC4zMTMzOTI5IDY3Ljg5MzQ2MiAxNy43NTczODM2IDY0LjQ0MjUyNzEgMTEuMzc1Ij48L3BvbHlnb24+CiAgICAgICAgICAgICAgICAgICAgPC9nPgogICAgICAgICAgICAgICAgPC9nPgogICAgICAgICAgICA8L2c+CiAgICAgICAgPC9nPgogICAgPC9nPgo8L3N2Zz4=">

</div>

</a>

</div>

</nav>

</div>

上手教程

<li class="toctree-l2"><a class="reference internal" href="announcement.html">官宣：Python 异步编程再添一利器</a></li>

<li class="toctree-l2 current"><a class="current reference internal" href="#">搭建一个 FastAPI 服务器</a></li>

</ul>

</li>

<li class="toctree-l1"><a class="reference internal" href="announcement.html">官宣：Python 异步编程再添一利器</a></li>

<li class="toctree-l1 current"><a class="current reference internal" href="#">搭建一个 FastAPI 服务器</a></li>

</ul>

进阶用法

<ul>

<li class="toctree-l1"><a class="reference internal" href="../how-to/alembic.html">使用 Alembic</a></li>

<li class="toctree-l1"><a class="reference internal" href="../how-to/loaders.html">加载器与关系</a></li>

<li class="toctree-l1"><a class="reference internal" href="../how-to/schema.html">表结构定义</a></li>

<li class="toctree-l1"><a class="reference internal" href="../how-to/transaction.html">数据库事务</a></li>

</ul>

原理说明

<ul>

<li class="toctree-l1"><a class="reference internal" href="../explanation/async.html">异步编程基础</a></li>

<li class="toctree-l1"><a class="reference internal" href="../explanation/engine.html">引擎与连接</a></li>

<li class="toctree-l1"><a class="reference internal" href="../explanation/sa20.html">SQLAlchemy 2.0</a></li>

<li class="toctree-l1"><a class="reference internal" href="../explanation/why.html">为什么要用异步 ORM？</a></li>

</ul>

参考手册

<ul>

</ul>

</div>

</header>

<main>

<h1>搭建一个 FastAPI 服务器<a class="headerlink" href="#build-a-fastapi-server" title="永久链接至标题">¶</a></h1>

在这篇教程里，我们会一起搭建一个用于生产环境的 <a class="reference external" href="https://fastapi.tiangolo.com/">FastAPI</a> 服务器。完整的示例代码在<a class="reference external" href="https://github.com/python-gino/gino-starlette/tree/master/examples/prod_fastapi_demo">这里</a> 。

写好之后，整个应用技术栈会是这样的：

<h2>创建一个新项目<a class="headerlink" href="#start-a-new-project" title="永久链接至标题">¶</a></h2>

这里我们尝试用亮瞎眼的 <a class="reference external" href="https://python-poetry.org/">Poetry</a> 来管理我们的项目，而不是传统的 pip。请跟随链接<a class="reference external" href="https://python-poetry.org/docs/#installation">安装 Poetry</a>，并且在一个空文件夹中创建我们的新项目：

<div class="highlight-console notranslate"><div class="highlight"><pre>$ mkdir gino-fastapi-demo

$ cd gino-fastapi-demo

$ git init

$ poetry init

</pre></div>

</div>

然后跟着 <a class="reference external" href="https://python-poetry.org/">Poetry</a> 的向导完成初始化——关于交互式创建依赖的两个问题，您可以回答“no”，因为我们会在下面手动创建。其他问题都可以用默认值，只是一定保证包的名字是 <code class="docutils literal notranslate">gino-fastapi-demo</code>。

</section>

<h2>添加依赖关系<a class="headerlink" href="#add-dependencies" title="永久链接至标题">¶</a></h2>

<a class="reference external" href="https://fastapi.tiangolo.com/">FastAPI</a> 底层用的是 <a class="reference external" href="https://www.starlette.io/">Starlette</a> 框架，所以我们就可以直接使用 <a class="reference external" href="https://github.com/python-gino/gino-starlette">GINO 的 Starlette 扩展</a>。执行以下命令即可：

<div class="highlight-console notranslate"><div class="highlight"><pre>$ poetry add gino[pg,starlette]

</pre></div>

</div>

接着我们添加 <a class="reference external" href="https://fastapi.tiangolo.com/">FastAPI</a>，以及快成一道闪电的 <a class="reference external" href="https://asgi.readthedocs.io/">ASGI</a> 服务器 <a class="reference external" href="https://www.uvicorn.org/">Uvicorn</a>，还有用作生产环境的应用服务器 <a class="reference external" href="https://gunicorn.org/">Gunicorn</a>：

<div class="highlight-console notranslate"><div class="highlight"><pre>$ poetry add fastapi uvicorn gunicorn

</pre></div>

</div>

我们将用 <a class="reference external" href="https://alembic.sqlalchemy.org/">Alembic</a> 来管理数据库表结构变更。因为 <a class="reference external" href="https://alembic.sqlalchemy.org/">Alembic</a> 只兼容传统的 <a class="reference external" href="https://www.python.org/dev/peps/pep-0249/">DB-API</a> 驱动，所以我们还得加上 <a class="reference external" href="https://www.psycopg.org/">psycopg</a>：

<div class="highlight-console notranslate"><div class="highlight"><pre>$ poetry add alembic psycopg2

</pre></div>

</div>

最后，测试框架选用 <a class="reference external" href="https://docs.pytest.org/">pytest</a>，我们将其添加到开发环境的依赖关系中。同时也加上 <a class="reference external" href="https://requests.readthedocs.io/">requests</a> 库，因为 <a class="reference external" href="https://www.starlette.io/">Starlette</a> 的 <a class="reference external" href="https://www.starlette.io/testclient/"><code class="docutils literal notranslate">TestClient</code></a> 要用到它：

<div class="highlight-console notranslate"><div class="highlight"><pre>$ poetry add -D pytest requests

</pre></div>

</div>

提示

经过了上面的步骤，<a class="reference external" href="https://python-poetry.org/">Poetry</a> 会悄没声地帮我们自动创建一个 <a class="reference external" href="https://virtualenv.pypa.io/">virtualenv</a>，并且把所有的依赖关系装到这个虚拟环境里。在本教程后面的步骤里，我们会假定继续使用这个环境。但是，您也可以创建自己的 <a class="reference external" href="https://virtualenv.pypa.io/">virtualenv</a>，只要激活了 <a class="reference external" href="https://python-poetry.org/">Poetry</a> 就会用它。

</div>

以上。下面是 <a class="reference external" href="https://python-poetry.org/">Poetry</a> 给我创建出来的 <code class="docutils literal notranslate">pyproject.toml</code> 文件内容，您的应该也长得差不多：

<div class="highlight-toml notranslate"><div class="highlight"><pre>[tool.poetry]

name = "gino-fastapi-demo"

version = "0.1.0"

description = ""

authors = ["Fantix King <fantix.king@gmail.com>"]

[tool.poetry.dependencies]

python = "^3.8"

gino = {version = "^1.0", extras = ["pg", "starlette"]}

fastapi = "^0.54.1"

uvicorn = "^0.11.3"

gunicorn = "^20.0.4"

alembic = "^1.4.2"

psycopg2 = "^2.8.5"

[tool.poetry.dev-dependencies]

pytest = "^5.4.1"

requests = "^2.23.0"

[build-system]

requires = ["poetry>=0.12"]

build-backend = "poetry.masonry.api"

</pre></div>

</div>

<img alt="../_images/gino-fastapi-poetry.svg" class="align-right" src="../_images/gino-fastapi-poetry.svg" />同时自动生成的还有一个叫 <code class="docutils literal notranslate">poetry.lock</code> 的文件，内容是当前完整依赖关系树的精确版本号，当前的目录结构如右图所示。现在让我们把这两个文件加到 Git 仓库中（以后的步骤就不再演示 Git 的操作了）：

<div class="highlight-console notranslate"><div class="highlight"><pre>$ git add pyproject.toml poetry.lock

$ git commit -m 'add project dependencies'

</pre></div>

</div>

</section>

<h2>编写一个简单的服务器<a class="headerlink" href="#write-a-simple-server" title="永久链接至标题">¶</a></h2>

现在让我们写一点 Python 的代码吧。

我们要创建一个 <code class="docutils literal notranslate">src</code> 文件夹，用来装所有的 Python 文件，如下图所示。这种目录结构叫做“<a class="reference external" href="https://hynek.me/articles/testing-packaging/">src 布局</a>”，能让项目结构更清晰。

<img alt="../_images/gino-fastapi-src.svg" class="align-right" src="../_images/gino-fastapi-src.svg" />我们项目的顶层 Python 包叫做 <code class="docutils literal notranslate">gino_fastapi_demo</code>，我们在里面创建两个 Python 模块：

<li><code class="docutils literal notranslate">asgi</code> 作为 ASGI 的入口，将被 ASGI 服务器直接使用</li>

<li><code class="docutils literal notranslate">main</code> 用来初始化我们自己的服务器</li>

</ul>

下面是 <code class="docutils literal notranslate">main.py</code> 的内容：

<div class="highlight-default notranslate"><div class="highlight"><pre>from fastapi import FastAPI

def get_app():

app = FastAPI(title="GINO FastAPI Demo")

return app

</pre></div>

</div>

在 <code class="docutils literal notranslate">asgi.py</code> 里，我们只需要实例化我们的应用即可：

<div class="highlight-default notranslate"><div class="highlight"><pre>from .main import get_app

app = get_app()

</pre></div>

</div>

然后执行 <code class="docutils literal notranslate">poetry install</code> 来把我们的 Python 包以开发模式链接到 <code class="docutils literal notranslate">PYTHONPATH</code> 中，接下来就可以启动 Uvicorn 的开发服务器了：

<div class="highlight-console notranslate"><div class="highlight"><pre>$ poetry install

Installing dependencies from lock file

No dependencies to install or update

- Installing gino-fastapi-demo (0.1.0)

$ poetry run uvicorn gino_fastapi_demo.asgi:app --reload

INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

INFO: Started reloader process [53010]

INFO: Started server process [53015]

INFO: Waiting for application startup.

INFO: Application startup complete.

</pre></div>

</div>

这里的 <code class="docutils literal notranslate">--reload</code> 选项会启用 Uvicorn 的自动加载功能，当我们的 Python 代码发生变动的时候，Uvicorn 会自动加载使用新代码。现在可以访问 <a class="reference external" href="http://127.0.0.1:8000/docs">http://127.0.0.1:8000/docs</a> 了，试一下我们新 FastAPI 服务器的 Swagger UI 接口文档。

提示

正如之前提到的，如果您使用自己的虚拟环境，那么此处的 <code class="docutils literal notranslate">poetry run uvicorn</code> 就可以简化为 <code class="docutils literal notranslate">uvicorn</code>。

<code class="docutils literal notranslate">poetry run</code> 是一个快捷命令，用于在 Poetry 管理的虚拟环境中执行后续的命令。

</div>

</section>

<img alt="../_images/gino-fastapi-config.svg" class="align-right" src="../_images/gino-fastapi-config.svg" />现在让我们把 GINO 添加到服务器里。

首先，我们需要有办法来配置数据库。在本教程中，我们选用 <a class="reference external" href="https://www.starlette.io/">Starlette</a> 的<a class="reference external" href="https://www.starlette.io/config/">配置系统</a>。创建文件 <code class="docutils literal notranslate">src/gino_fastapi_demo/config.py</code>，内容为：

<div class="highlight-default notranslate"><div class="highlight"><pre>from sqlalchemy.engine.url import URL, make_url

from starlette.config import Config

from starlette.datastructures import Secret

config = Config(".env")

DB_DRIVER = config("DB_DRIVER", default="postgresql")

DB_HOST = config("DB_HOST", default=None)

DB_PORT = config("DB_PORT", cast=int, default=None)

DB_USER = config("DB_USER", default=None)

DB_PASSWORD = config("DB_PASSWORD", cast=Secret, default=None)

DB_DATABASE = config("DB_DATABASE", default=None)

DB_DSN = config(

"DB_DSN",

cast=make_url,

default=URL(

drivername=DB_DRIVER,

username=DB_USER,

password=DB_PASSWORD,

host=DB_HOST,

port=DB_PORT,

database=DB_DATABASE,

),

)

DB_POOL_MIN_SIZE = config("DB_POOL_MIN_SIZE", cast=int, default=1)

DB_POOL_MAX_SIZE = config("DB_POOL_MAX_SIZE", cast=int, default=16)

DB_ECHO = config("DB_ECHO", cast=bool, default=False)

DB_SSL = config("DB_SSL", default=None)

DB_USE_CONNECTION_FOR_REQUEST = config(

"DB_USE_CONNECTION_FOR_REQUEST", cast=bool, default=True

)

DB_RETRY_LIMIT = config("DB_RETRY_LIMIT", cast=int, default=1)

DB_RETRY_INTERVAL = config("DB_RETRY_INTERVAL", cast=int, default=1)

</pre></div>

</div>

这个配置文件会首先从环境变量中加载配置参数，如果没找到，则会从当前路径（通常是项目顶层目录）下一个叫 <code class="docutils literal notranslate">.env</code> 的文件中加载，最后不行才会使用上面定义的默认值。比如，您即可以在命令行中设置：

<div class="highlight-console notranslate"><div class="highlight"><pre>$ DB_HOST=localhost DB_USER=postgres poetry run uvicorn gino_fastapi_demo.asgi:app --reload

</pre></div>

</div>

<img alt="../_images/gino-fastapi-env.svg" class="align-right" src="../_images/gino-fastapi-env.svg" />也可以在 <code class="docutils literal notranslate">.env</code> 文件中设置（一定不要将该文件提交到 Git 中，记得在 <code class="docutils literal notranslate">.gitignore</code> 里加上它）：

<div class="highlight-bash notranslate"><div class="highlight"><pre>DB_HOST=localhost

DB_USER=postgres

</pre></div>

</div>

接下来就该创建 <a class="reference external" href="https://www.postgresql.org/">PostgreSQL</a> 数据库实例并且将连接参数设置好了。创建数据库实例的命令通常是 <code class="docutils literal notranslate">createdb yourdbname</code>，但不同平台可能有不同的方式，此教程里就不具体写了。

小技巧

另外，您也可以使用 <code class="docutils literal notranslate">DB_DSN</code> 来定义数据库连接参数，比如 <code class="docutils literal notranslate">postgresql://user:password@localhost:5432/dbname</code>，它会覆盖出现在它前面的单个的配置，比如 <code class="docutils literal notranslate">DB_HOST</code>。

除了默认值不算之外，只要您定义了 <code class="docutils literal notranslate">DB_DSN</code> ——不管是在环境变量中还是在 <code class="docutils literal notranslate">.env</code> 文件中，它都比单个的连接参数有更高的优先级。比如哪怕环境变量中定义了 <code class="docutils literal notranslate">DB_HOST</code>，<code class="docutils literal notranslate">.env</code> 文件中的 <code class="docutils literal notranslate">DB_DSN</code> 仍然能够覆盖前者的值。

</div>

<img alt="../_images/gino-fastapi-models.svg" class="align-right" src="../_images/gino-fastapi-models.svg" />然后创建一个 Python 的二级包 <code class="docutils literal notranslate">gino_fastapi_demo.models</code>，用来封装数据库相关的代码。将下面的代码添加到 <code class="docutils literal notranslate">src/gino_fastapi_demo/models/__init__.py</code>：

<div class="highlight-default notranslate"><div class="highlight"><pre>from gino.ext.starlette import Gino

from .. import config

db = Gino(

dsn=config.DB_DSN,

pool_min_size=config.DB_POOL_MIN_SIZE,

pool_max_size=config.DB_POOL_MAX_SIZE,

echo=config.DB_ECHO,

ssl=config.DB_SSL,

use_connection_for_request=config.DB_USE_CONNECTION_FOR_REQUEST,

retry_limit=config.DB_RETRY_LIMIT,

retry_interval=config.DB_RETRY_INTERVAL,

)

</pre></div>

</div>

最后，修改 <code class="docutils literal notranslate">src/gino_fastapi_demo/main.py</code>，安装 GINO 扩展：

<div class="highlight-diff notranslate"><div class="highlight"><pre> from fastapi import FastAPI

+

+from .models import db

def get_app():

app = FastAPI(title="GINO FastAPI Demo")

+ db.init_app(app)

return app

</pre></div>

</div>

保存该文件后，您应该可以看到 Uvicorn 服务器重载了我们的变更，然后连上了数据库：

<div class="highlight-console notranslate"><div class="highlight"><pre>WARNING: Detected file change in 'src/gino_fastapi_demo/main.py'. Reloading...

INFO: Shutting down

INFO: Waiting for application shutdown.

INFO: Application shutdown complete.

INFO: Finished server process [63562]

INFO: Started server process [63563]

INFO: Waiting for application startup.

INFO: Connecting to the database: postgresql://fantix:***@localhost

INFO: Database connection pool created: <asyncpg.pool.Pool max=16 min=1 cur=1 use=0>

INFO: Application startup complete.

</pre></div>

</div>

</section>

<h2>创建 model 及 API<a class="headerlink" href="#create-models-and-api" title="永久链接至标题">¶</a></h2>

<img alt="../_images/gino-fastapi-models-users.svg" class="align-right" src="../_images/gino-fastapi-models-users.svg" />现在轮到实现 API 逻辑了。比方说我们打算做一个用户管理的服务，可以添加、查看和删除用户。

首先，我们需要一张数据库表 <code class="docutils literal notranslate">users</code>，用于存储数据。在 <code class="docutils literal notranslate">gino_fastapi_demo.models.users</code> 模块中添加一个映射这张表的 model <code class="docutils literal notranslate">User</code>：

<div class="highlight-default notranslate"><div class="highlight"><pre>from . import db

class User(db.Model):

__tablename__ = "users"

id = db.Column(db.BigInteger(), primary_key=True)

nickname = db.Column(db.Unicode(), default="unnamed")

</pre></div>

</div>

<img alt="../_images/gino-fastapi-views.svg" class="align-right" src="../_images/gino-fastapi-views.svg" />很简单的 model 定义，一切尽在不言中。

然后我们只需要在 API 的实现中正确使用它即可。创建一个新的 Python 二级包 <code class="docutils literal notranslate">gino_fastapi_demo.models.views</code>，在其中添加一个模块 <code class="docutils literal notranslate">gino_fastapi_demo.views.users</code>，内容为：

from pydantic import BaseModel

from ..models.users import User

router = APIRouter()

@router.get("/users/{uid}")

async def get_user(uid: int):

user = await User.get_or_404(uid)

return user.to_dict()

class UserModel(BaseModel):

name: str

@router.post("/users")

async def add_user(user: UserModel):

rv = await User.create(nickname=user.name)

return rv.to_dict()

@router.delete("/users/{uid}")

async def delete_user(uid: int):

await user.delete()

return dict(id=uid)

def init_app(app):

app.include_router(router)

</pre></div>

</div>

<a class="reference external" href="https://fastapi.tiangolo.com/tutorial/bigger-applications/#apirouter"><code class="docutils literal notranslate">APIRouter</code></a> 用来收集新接口的定义，然后在 <code class="docutils literal notranslate">init_app</code> 里集成到 FastAPI 应用中去。这里我们加一点<a class="reference external" href="https://en.wikipedia.org/wiki/Inversion_of_control">反转控制</a> ：把接口做成模块化的，用 <a class="reference external" href="https://docs.python.org/3/library/importlib.metadata.html#entry-points">Entry Points</a> 功能进行拼装，避免需要手动一一 import 将来可能有的其他接口。将下面的代码添加到 <code class="docutils literal notranslate">gino_fastapi_demo.main</code>：

<div class="highlight-default notranslate"><div class="highlight"><pre>import logging

from importlib.metadata import entry_points

logger = logging.getLogger(__name__)

def load_modules(app=None):

for ep in entry_points()["gino_fastapi_demo.modules"]:

logger.info("Loading module: %s", ep.name)

mod = ep.load()

if app:

init_app = getattr(mod, "init_app", None)

if init_app:

init_app(app)

</pre></div>

</div>

提示

如果您的 Python 版本低于 3.8，您还需要这个 <a class="reference external" href="https://importlib-metadata.readthedocs.io/">importlib-metadata 的移植</a>。

</div>

然后在我们的应用工厂函数中调用它：

<div class="highlight-diff notranslate"><div class="highlight"><pre> def get_app():

app = FastAPI(title="GINO FastAPI Demo")

db.init_app(app)

+ load_modules(app)

return app

</pre></div>

</div>

最后，根据 <a class="reference external" href="https://python-poetry.org/docs/pyproject/#plugins">Poetry 插件文档</a>，在 <code class="docutils literal notranslate">pyproject.toml</code> 文件中定义 Entry Point：

<div class="highlight-toml notranslate"><div class="highlight"><pre>[tool.poetry.plugins."gino_fastapi_demo.modules"]

"users" = "gino_fastapi_demo.views.users"

</pre></div>

</div>

再执行一次 <code class="docutils literal notranslate">poetry install</code> 来激活这些 Entry Point——这次您可能需要亲自重启 <a class="reference external" href="https://www.uvicorn.org/">Uvicorn</a> 的开发服务器了，因为自动重载机制无法识别 <code class="docutils literal notranslate">pyproject.toml</code> 文件的变更。

现在您应该可以在 Swagger UI 中看到那 3 个新接口了，但是它们还都不能用，因为我们还没有创建数据库表。

</section>

<h2>集成 Alembic<a class="headerlink" href="#integrate-with-alembic" title="永久链接至标题">¶</a></h2>

请在项目顶层文件夹中执行下面的命令，以开始使用 <a class="reference external" href="https://alembic.sqlalchemy.org/">Alembic</a>：

<div class="highlight-console notranslate"><div class="highlight"><pre>$ poetry run alembic init migrations

</pre></div>

</div>

<img alt="../_images/gino-fastapi-alembic.svg" class="align-right" src="../_images/gino-fastapi-alembic.svg" />这句命令会生产一个新的文件夹 <code class="docutils literal notranslate">migrations</code>，包含了 <a class="reference external" href="https://alembic.sqlalchemy.org/">Alembic</a> 用于数据库表结构变更追踪的版本文件。同时创建的还有一个在顶层文件夹下面的 <code class="docutils literal notranslate">alembic.ini</code> 文件，我们把这些文件都添加到 Git 中。

为了能让 <a class="reference external" href="https://alembic.sqlalchemy.org/">Alembic</a> 用上我们用 GINO 定义的 model，我们需要修改 <code class="docutils literal notranslate">migrations/env.py</code> 文件去链接 GINO 实例：

<div class="highlight-diff notranslate"><div class="highlight"><pre> # add your model's MetaData object here

# for 'autogenerate' support

# from myapp import mymodel

# target_metadata = mymodel.Base.metadata

-target_metadata = None

+from gino_fastapi_demo.config import DB_DSN

+from gino_fastapi_demo.main import db, load_modules

+

+load_modules()

+config.set_main_option("sqlalchemy.url", str(DB_DSN))

+target_metadata = db

</pre></div>

</div>

然后就可以创建我们的第一个变更版本了：

<div class="highlight-console notranslate"><div class="highlight"><pre>$ poetry run alembic revision --autogenerate -m 'add users table'

INFO [alembic.runtime.migration] Context impl PostgresqlImpl.

INFO [alembic.runtime.migration] Will assume transactional DDL.

INFO [alembic.autogenerate.compare] Detected added table 'users'

Generating migrations/versions/32c0feba61ea_add_users_table.py ... done

</pre></div>

</div>

生成的版本文件大体上应该长这样：

<div class="highlight-default notranslate"><div class="highlight"><pre>def upgrade():

op.create_table(

"users",

sa.Column("id", sa.BigInteger(), nullable=False),

sa.Column("nickname", sa.Unicode(), nullable=True),

sa.PrimaryKeyConstraint("id"),

)

def downgrade():

op.drop_table("users")

</pre></div>

</div>

提示

以后需要再次修改数据库表结构的时候，您只需要修改 GINO model 然后执行 <code class="docutils literal notranslate">alembic revision --autogenerate</code> 命令来生成对应改动的新版本即可。提交前记得看一下生成的版本文件，有时需要调整。

</div>

我们终于可以应用此次变更了，执行下面的命令将数据库表结构版本升级至最高：

<div class="highlight-console notranslate"><div class="highlight"><pre>$ poetry run alembic upgrade head

INFO [alembic.runtime.migration] Context impl PostgresqlImpl.

INFO [alembic.runtime.migration] Will assume transactional DDL.

INFO [alembic.runtime.migration] Running upgrade -> 32c0feba61ea, add users table

</pre></div>

</div>

到这里，所有的接口应该都可以正常工作了，您可以在 Swagger UI 中试一下。

</section>

为了不影响开发环境的数据库，我们需要为测试创建单独的数据库。根据下面的补丁修改 <code class="docutils literal notranslate">gino_fastapi_demo.config</code>：

<div class="highlight-diff notranslate"><div class="highlight"><pre> config = Config(".env")

+TESTING = config("TESTING", cast=bool, default=False)

DB_DRIVER = config("DB_DRIVER", default="postgresql")

DB_HOST = config("DB_HOST", default=None)

DB_PORT = config("DB_PORT", cast=int, default=None)

DB_USER = config("DB_USER", default=None)

DB_PASSWORD = config("DB_PASSWORD", cast=Secret, default=None)

DB_DATABASE = config("DB_DATABASE", default=None)

+if TESTING:

+ if DB_DATABASE:

+ DB_DATABASE += "_test"

+ else:

+ DB_DATABASE = "gino_fastapi_demo_test"

DB_DSN = config(

</pre></div>

</div>

提示

您需要执行 <code class="docutils literal notranslate">createdb</code> 来创建数据库实例。比如说，如果您在 <code class="docutils literal notranslate">.env</code> 文件中定义了 <code class="docutils literal notranslate">DB_DATABASE=mydb</code>，那么测试数据库的名字就是 <code class="docutils literal notranslate">mydb_test</code>。否则如果没定义的话，默认就是 <code class="docutils literal notranslate">gino_fastapi_demo_test</code>。

</div>

然后在 <code class="docutils literal notranslate">tests/conftest.py</code> 中创建 <a class="reference external" href="https://docs.pytest.org/">pytest</a> fixture：

<div class="highlight-default notranslate"><div class="highlight"><pre>import pytest

from alembic.config import main

from starlette.config import environ

from starlette.testclient import TestClient

environ["TESTING"] = "TRUE"

@pytest.fixture

def client():

from gino_fastapi_demo.main import db, get_app

main(["--raiseerr", "upgrade", "head"])

with TestClient(get_app()) as client:

yield client

main(["--raiseerr", "downgrade", "base"])

</pre></div>

</div>

<img alt="../_images/gino-fastapi-tests.svg" class="align-right" src="../_images/gino-fastapi-tests.svg" />这个 fixture 的作用是，在跑测试之前创建所有的数据库表、提供一个 <a class="reference external" href="https://www.starlette.io/">Starlette</a> 的 <a class="reference external" href="https://www.starlette.io/testclient/"><code class="docutils literal notranslate">TestClient</code></a>、并且在测试跑完之后删除所有的表及其数据，为后续测试保持一个干净的环境。

下面是一个简单的测试例子，<code class="docutils literal notranslate">tests/test_users.py</code>：

<div class="highlight-default notranslate"><div class="highlight"><pre>import uuid

def test_crud(client):

# create

nickname = str(uuid.uuid4())

r = client.post("/users", json=dict(name=nickname))

r.raise_for_status()

# retrieve

url = f"/users/{r.json()['id']}"

assert client.get(url).json()["nickname"] == nickname

# delete

client.delete(url).raise_for_status()

assert client.get(url).status_code == 404

</pre></div>

</div>

测试跑起来：

<div class="highlight-console notranslate"><div class="highlight"><pre>$ poetry run pytest

=========================== test session starts ===========================

platform darwin -- Python 3.8.2, pytest-5.4.1, py-1.8.1, pluggy-0.13.1

rootdir: gino-fastapi-demo

collected 1 item

tests/test_users.py . [100%]

============================ 1 passed in 1.21s ============================

</pre></div>

</div>

</section>

<h2>生产环境注意事项<a class="headerlink" href="#notes-for-production" title="永久链接至标题">¶</a></h2>

最近 Docker/Kubernetes 挺火，我们也写一个 <code class="docutils literal notranslate">Dockerfile</code>：

<div class="highlight-dockerfile notranslate"><div class="highlight"><pre>FROM python:3.8-alpine as base

FROM base as builder

RUN apk add --no-cache gcc musl-dev libffi-dev openssl-dev make postgresql-dev

RUN pip install poetry

COPY . /src/

WORKDIR /src

RUN python -m venv /env && . /env/bin/activate && poetry install

FROM base

RUN apk add --no-cache postgresql-libs

COPY --from=builder /env /env

COPY --from=builder /src /src

WORKDIR /src

CMD ["/env/bin/gunicorn", "gino_fastapi_demo.asgi:app", "-b", "0.0.0.0:80", "-k", "uvicorn.workers.UvicornWorker"]

</pre></div>

</div>

这个 <code class="docutils literal notranslate">Dockerfile</code> 里，为了降低目标镜像文件的大小，我们分成了两步来分别进行源码构建和生产镜像的组装。另外，我们还采用了 <a class="reference external" href="https://gunicorn.org/">Gunicorn</a> 搭配 <a class="reference external" href="https://www.uvicorn.org/">Uvicorn</a> 的 <a class="reference external" href="https://www.uvicorn.org/deployment/#gunicorn"><code class="docutils literal notranslate">UvicornWorker</code></a> 的方式来获取最佳生产级别可靠性。

回头看一下项目里一共有哪些文件。

<img alt="../_images/gino-fastapi-layout.svg" class="align-center" src="../_images/gino-fastapi-layout.svg" />至此，我们就完成了演示项目的开发。下面是上生产可以用到的一个不完整检查清单：

<li>将 <code class="docutils literal notranslate">DB_RETRY_LIMIT</code> 设置成一个稍微大一点的数字，以支持在数据库就绪前启动应用服务器的情况。</li>

<li>在 <code class="docutils literal notranslate">migrations/env.py</code> 中实现同样的重连尝试逻辑，这样 <a class="reference external" href="https://alembic.sqlalchemy.org/">Alembic</a> 也能拥有同样的特性。</li>

<li>如果需要的话，启用 <code class="docutils literal notranslate">DB_SSL</code>。</li>

<li>写一个 <code class="docutils literal notranslate">docker-compose.yml</code>，用于其他开发人员快速尝鲜，甚至可以用于开发。</li>

<li>启用<cite>持续集成 <CI_></cite>，安装 <code class="docutils literal notranslate">pytest-cov</code> 并且用 <code class="docutils literal notranslate">--cov-fail-under</code> 参数来保障测试覆盖率。</li>

<li>集成静态代码检查工具和安全性/CVE筛查工具。</li>

<li>正确自动化 <a class="reference external" href="https://alembic.sqlalchemy.org/">Alembic</a> 的升级流程，比如在每次新版本部署之后执行。</li>

<li>注意针对诸如 <a class="reference external" href="https://en.wikipedia.org/wiki/Cross-site_request_forgery">CSRF</a>、<a class="reference external" href="https://en.wikipedia.org/wiki/Cross-site_scripting">XSS</a> 等常见攻击的安全性防护。</li>

<li>编写压力测试。</li>

</ul>

最后再贴一次，实例程序的源码在<a class="reference external" href="https://github.com/python-gino/gino-starlette/tree/master/examples/prod_fastapi_demo">这里</a>，本教程的文档源码在<a href="#id1">`这里<https://github.com/python-gino/gino/blob/master/docs/tutorials/fastapi.rst>`__</a>，请敞开了提 PR，修问题或者分享想法都行。祝玩得愉快！

</section>

</div>

<img

alt="知识共享许可协议"

style="border-width:0"

src="https://i.creativecommons.org/l/by-sa/4.0/80x15.png"

</a>

本作品采用<a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/">知识共享署名-相同方式共享 4.0 国际许可协议</a>进行许可。

</div>

<ul>

<li><a class="reference internal" href="#">搭建一个 FastAPI 服务器</a><ul>

<li><a class="reference internal" href="#start-a-new-project">创建一个新项目</a></li>

<li><a class="reference internal" href="#add-dependencies">添加依赖关系</a></li>

<li><a class="reference internal" href="#write-a-simple-server">编写一个简单的服务器</a></li>

<li><a class="reference internal" href="#create-models-and-api">创建 model 及 API</a></li>

<li><a class="reference internal" href="#integrate-with-alembic">集成 Alembic</a></li>

<li><a class="reference internal" href="#notes-for-production">生产环境注意事项</a></li>

</ul>

</li>

</ul>

<hr>

您正在浏览 master 分支，该文档可能涉及尚未发布的功能。

</div>

<a href="https://www.transifex.com/decentfox-studio/gino_1_0/"

target="_blank">Add your language here.</a>

</div>

<div>

</div>

</a>

</ul>

</div>

</main>

var sver = 'master';

var language = 'zh';

var pagename = 'tutorials/fastapi';

</script>

</body>

</html>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

fastapi.html

Latest commit

History

fastapi.html

File metadata and controls