Ckli的blog

从零构建共享API平台：基于Swoft 2.0的微服务架构实践

Thu, 12 Feb 2026 18:54:25 +0800

<本文介绍如何基于Swoft 2.0框架>

<构建共享API网关平台，探讨公益与技术,商业化的平衡之道。>

## 前言

做公益这件事，我走了好多年。中间有过委屈，有过难，甚至看着自己搭建的平台，明明能帮人，却因"不会吆喝"而少有人问津时，也会陷入迷茫。但每当想起乡镇里，有人为了赶一趟班车，天不亮就守在路边；残障朋友想找份能做的活，却被大平台的门槛挡在门外；还有那些假期里，为买不到票、怕堵车而发愁的乡亲们，我又觉得这件事必须得做下去。

——摘自《七家坡的"摆渡人"》

作为一名在PHP领域深耕近20年的后端工程师，我一直在思考：如何用技术力量帮助更多人，同时又能让技术实现可持续发展？本文将分享我基于Swoft 2.0框架构建共享API平台的实践经验。

## 项目背景

我的共享API平台目前已经支撑了多个公益项目：

- **七家坡基层互助站** (https://lo.lck.yn.cn/)

提共基于用户当前位置（查询、发布）拼车、运营（车辆、路线）信息等便民服务

- **AI合集** (https://ai.lck.yn.cn/)

基于AI的（含八字算命，将持续增加更多服务）传统文化服务

这些项目虽然面向不同场景，但都需要相同的底层能力：用户认证、地理定位、支付、数据存储等。为了避免重复造轮子，我决定构建一个**共享API平台**，让所有项目都能快速接入这些通用能力。

## 技术选型：为什么选择Swoft 2.0？

在选型时，我对比了多个PHP框架：

| 框架 | 协程支持 | 微服务 | 学习成本 | 性能 |

|------|---------|--------|---------|------|

| Laravel | 无 | 无 | 低 | 中 |

| Hyperf | 有 | 有 | 中 | 高 |

| Swoft 2.0 | 有 | 有 | 中 | 高 |

最终选择**Swoft 2.0**的原因：

1. **成熟的协程支持**：基于Swoole扩展，提供原生协程能力，性能接近Go语言

2. **gRPC原生支持**：内置gRPC支持，可与任何语言无缝对接

3. **微服务架构**：内置RPC服务注册与发现，完美契合我的分布式架构需求

4. **注解驱动**：类似Spring Cloud的注解机制，代码简洁优雅

5. **完善的生态**：内置连接池、AOP、任务调度等企业级功能

### 关于框架选择的真实思考

**Swoft 2.0的现状**：

- 官方早已停止维护，官网已无法访问

- 基本查不到相关资料，社区支持很少

- 很多功能文档缺失，需要自己摸索

**为什么还是选择了它？**

1. **协程性能优势**：Swoole扩展的性能优势难以替代

2. **架构设计优秀**：微服务、RPC、注解机制的设计理念先进

3. **自主掌控**：既然官方不维护，我就自己维护

**填坑之路**：

- 很多功能的实现方案，AI都无法给出正确答案

- 每个坑都花了超过一周的时间去研究、测试、验证

- 通过理解作者意图、结合实战经验、深入底层源码，最终全部实现

**给后来者的建议**：

技术选型不要盲目追求"官方维护"，关键是否适合你的场景。

框架只是工具，你的技术积累和解决问题的能力才是核心。

## 架构设计

### 整体架构

```

┌──────────────────────┐

│ 前端应用层 │

│ ┌────────┐┌────────┐│

│ │七家坡 ││AI站点 ││

│ └────────┘└────────┘│

└──────────────────────┘

│

▼

┌──────────────────────┐

│ API网关层 │

│ Gateway │

│ - JWT认证 │

│ - 权限控制 │

│ - 限流 │

│ - 日志审计 │

└──────────────────────┘

│

▼

┌──────────────────────┐

│ 微服务层 │

│ ┌────┐┌────┐┌────┐│

│ │Traf││Stay││Admi││

│ │fic ││ ││n ││

│ └────┘└────┘└────┘│

└──────────────────────┘

│

▼

┌──────────────────────┐

│ 数据存储层 │

│ ┌────┐┌────┐┌────┐│

│ │MyS ││Redi││支付││

│ │QL ││s ││接口││

│ └────┘└────┘└────┘│

└──────────────────────┘

```

### 服务拆分

根据业务领域，我将服务拆分为以下模块（端口为示意配置，实际部署时可自定义）：

**网关层：**

| 服务 | 职责 | 端口 |

|------|------|------|

| **gateway** | API网关，负责认证、路由、限流、域名授权 | 80 |

**微服务层：**

| 服务 | 职责 | 包含的子服务 |

|------|------|-------------|

| **login** | 登录服务 | 登录 |

| **user** | 用户服务 | 用户、地址等 |

| **code** | 验证服务 | 邮箱验证、短信验证（已测试通过） |

| **category** | 分类服务 | 分类 |

| **traffic** | 交通服务 | 拼车、运营（岗位信息） |

| **stay** | 住宿服务 | 小屋（民宿） |

| **aigc** | AI合集服务 | 八字取名等AI服务 |

| **pay** | 支付服务 | 订单、支付回调 |

共 **8个微服务**，每个服务下可能有1或多个子服务。

## 核心功能实现

### 1. API网关设计

网关是整个系统的入口，负责：

- **JWT认证**：基于`Swoft\Auth`组件实现，支持token自动刷新

- **域授权机制**：根据请求来源域名进行授权控制

- **本地开发友好**：localhost/127.0.0.1等本地域名默认已授权

- **权限控制**：通过中间件拦截未授权请求

- **服务路由**：将请求转发到对应的微服务

- **限流保护**：使用`Swoft\Limiter`防止接口滥用

- **文档生成**：自动生成Swagger文档

网关配置示例（`config/beans.php`）：

```php

return [

'userAuth' => [

'class' => Swoft\Auth\Manager::class,

'name' => 'user',

'language' => 'zh',

'ttl' => 7200, // token有效期2小时

'refreshTtl' => 2592000, // 刷新token有效期30天

'jwtAuth' => [

'class' => Swoft\Auth\Parser\JWTAuthParser::class,

]

];

```

**Token自动刷新机制**：

```php

// 中间件中实现token自动刷新

public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface

{

$token = $this->jwtAuth->parse($request);

$payload = $token->payload();

// 检查token是否即将过期（剩余时间小于10分钟）

if ($payload['exp'] - time() < 600) {

$newToken = $this->auth->refreshToken($token);

// 在响应头中返回新token

return $handler->handle($request)->withHeader('X-New-Token', $newToken);

}

return $handler->handle($request);

}

```

### 2. 地理位置查询优化（LBS）

顺风车和民宿服务都需要根据用户位置查询附近信息。这是典型的地理围栏查询场景。

#### 优化前的问题

传统使用`HAVING`计算距离的方式效率低下：

```sql

SELECT *,

(6371 * ACOS(

COS(RADIANS(lat)) * COS(RADIANS(24.88)) *

COS(RADIANS(lng) - RADIANS(102.83)) +

SIN(RADIANS(lat)) * SIN(RADIANS(24.88))

)) AS distance

FROM sys_carpooling

HAVING distance < 10

ORDER BY distance

```

**问题**：

- 每次查询都要计算全表距离，性能极差

- 无法使用索引，随着数据量增加性能急剧下降

#### 优化方案

采用**边界框预过滤 + 空间索引**的双重优化策略：

```sql

SELECT *,

ST_Distance_Sphere(

location,

ST_GeomFromText('POINT(102.83 24.88)')

) AS distance

FROM sys_carpooling

WHERE lat BETWEEN 24.01 AND 25.75

AND lng BETWEEN 101.91 AND 103.75

AND ST_Distance_Sphere(

location,

POINT(102.83, 24.88)

) <= 10000

ORDER BY distance

LIMIT 20

```

**优化要点**：

1. **添加空间索引**：

```sql

ALTER TABLE sys_carpooling

ADD COLUMN location POINT NOT NULL COMMENT '位置坐标' AFTER lat,

ADD SPATIAL INDEX idx_location (location);

```

2. **范围级别参数化**：

```php

$rangeMap = [

1 => 10, // 10公里

2 => 50, // 50公里

3 => 100, // 100公里（默认）

];

$range = $rangeMap[$level] ?? 100;

```

3. **计算边界框**：

```php

$lngMin = $lng - $range / 111.32 / cos($lat * PI() / 180);

$lngMax = $lng + $range / 111.32 / cos($lat * PI() / 180);

$latMin = $lat - $range / 111.32;

$latMax = $lat + $range / 111.32;

```

**性能对比**：

| 数据量 | 优化前 | 优化后 | 提升 |

|--------|--------|--------|------|

| 1万条 | 2.5s | 0.05s | 50x |

| 10万条 | 25s | 0.08s | 312x |

### 3. RPC微服务通信

平台支持**gRPC协议**，这是微服务通信的最佳选择。

#### 为什么选择gRPC？

gRPC相比传统HTTP API有以下优势：

| 特性 | HTTP/REST | gRPC |

|------|-----------|------|

| 协议 | 文本(JSON) | 二进制(Protobuf) |

| 传输效率 | 低（数据大） | 高（数据小） |

| 序列化速度 | 慢 | 快（5-10倍） |

| 跨语言支持 | 需要手动适配 | 自动生成代码 |

| 流式传输 | 不支持 | 支持（单向流/双向流） |

| 代码量 | 手动解析 | 自动生成 |

**关键优势**：

- **任何语言对接**：支持Go、Java、Python、Node.js、C#、PHP等20+种语言

- **协程友好**：完美配合Swoole协程，无阻塞

- **内存运行**：常驻内存，无需每次请求启动

- **性能更快**：二进制协议，传输速度提升3-5倍

- **资源占用少**：相比传统HTTP API，内存占用降低50%以上

服务间通过RPC调用，Swoft提供了优雅的注解方式：

**定义Proto文件**（`traffic.proto`）：

```protobuf

syntax = "proto3";

package traffic;

service TrafficService {

rpc NearList(NearRequest) returns (NearResponse);

rpc CreateCarpooling(CarpoolingRequest) returns (CommonResponse);

}

message NearRequest {

float lng = 1;

float lat = 2;

int32 level = 3;

}

message NearResponse {

repeated Carpooling items = 1;

int32 total = 2;

}

```

**PHP服务端实现**：

```php

/**

* @RpcService(name="trafficService", version="1.0")

class TrafficService

{

/**

* 查询附近顺风车

public function nearList(float $lng, float $lat, int $level = 3): array

{

return CarpoolingDao::nearList($lng, $lat, $level);

}

```

**服务消费者通过`@Reference`注解注入**：

```php

/**

* @Reference(name="trafficService", version="1.0")

private $trafficService;

public function near(Request $request): Response

{

$data = $this->trafficService->nearList(

$request->get('lng'),

$request->get('lat'),

$request->get('level', 3)

);

return context()->getResponse()->withData($data);

}

```

**跨语言调用示例**：

```go

// Go客户端

conn, _ := grpc.Dial("localhost:8307", grpc.WithInsecure())

client := pb.NewTrafficServiceClient(conn)

req := &pb.NearRequest{

Lng: 102.83,

Lat: 24.88,

Level: 3,

}

resp, _ := client.NearList(context.Background(), req)

```

### 4. 支付系统集成

支付系统支持微信和支付宝，需要区分PC端和移动端：

```php

public function createOrder(Request $request): Response

{

$deviceType = getDeviceType(); // H5/Pc

// 支付方式判断

$method = $this->getPaymentMethod($channel, $deviceType);

// 微信PC端: Native, 支付宝PC端: PcWeb, 移动端: H5

$order = [

'ser_name' => 'aigc',

'amount' => $amount * 100, // 转为分

'channel' => $channel, // Wechat/Alipay

'method' => $method,

'body' => '套餐名称',

'source' => '总部自营',

'user_id' => $userId ?: null,

'temp_id' => $tempId ?: null,

];

return $this->orderApi->create($order);

}

```

### 5. 自动化部署

为了提高开发效率，我实现了完整的自动化部署流程：

```bash

# 部署脚本

#!/bin/bash

git pull origin master

composer install --no-dev

php bin/swoft stop

php bin/swoft start -d

```

Git提交后自动触发部署，无需人工干预。

## API文档管理

使用Swagger自动生成API文档，部署在：

- **生产环境**：https://api.micro.lck.yn.cn/

- **测试环境**：https://apitest.micro.lck.yn.cn/

## 接入模式与商业化思考

### 灵活的接入方式

平台提供两种接入模式，开发者可以根据项目发展阶段自由选择：

#### 1. 共享API模式（适合项目初期）

**适用场景**：

- 项目刚起步，用户量和并发较低

- 希望节省服务器和运维成本

- 快速验证商业想法

**优势**：

- **零运维成本**：无需搭建服务器、数据库等基础设施

- **快速上线**：5分钟即可完成接入

- **按需授权**：根据项目域名进行授权，灵活便捷

- **本地开发友好**：localhost等本地域名默认已授权，开发无忧

**授权方式**：

- 通过申请域名授权，绑定项目前端域名

- 本地开发环境（localhost、127.0.0.1）默认已授权

- 域名审核通过后，即可在生产环境使用

#### 2. 独立部署模式（适合项目成长期）

**适用场景**：

- 项目已有一定用户量和流量

- 需要更高的性能和稳定性

- 数据安全要求更高

**优势**：

- **完全独立**：网关、微服务、数据库全部独立部署

- **跨服务器架构**：可根据需要分布式部署

- **性能无上限**：根据业务需求灵活扩展

- **数据完全掌控**：所有数据存储在自有服务器

**部署灵活性**：

```

方式1：单机部署（小型项目）

┌──────────┐

│ 单服务器 │

└──────────┘

方式2：分布式部署（中型项目）

┌────┐┌────┐┌────┐

│网关││应用││数据库│

└────┘└────┘└────┘

方式3：集群部署（大型项目）

┌────┐┌────┐┌────┐

│网关││应用││数据库│

│集群││集群││集群 │

└────┘└────┘└────┘

```

### 无缝迁移路径

平台设计了平滑的迁移路径：

```

项目起步期 → 项目成长期 → 项目成熟期

共享API → 独立部署 → 完全私有化

(零成本) (逐步) (掌控)

```

**迁移优势**：

- **代码无需修改**：API接口保持一致

- **数据平滑迁移**：支持数据导出和导入

- **无缝切换**：域名授权即可切换模式

### 技术支持

提供多渠道技术支持：

- **微信**：kmwmkj

- **邮箱**：admin@lck.yn.cn

- **电话**：15687658489（微信同号）

### 公益与可持续

做公益不代表不能商业化，关键是找到平衡点：

**公益初心**：

- 始终记得为什么出发，不要因为商业化而偏离公益使命

- 为公益项目提供技术支持，降低公益项目的技术门槛

**可持续发展**：

- 公益也需要资金支持，合理的商业化能让平台走得更远

- 通过商业化项目反哺公益项目，形成良性循环

**开放共赢**：

- 欢迎更多公益项目接入，共同服务社会

- 建立开发者社区，共享技术资源和经验

## 经验总结

### 技术层面

1. **协程编程思维**：协程不是万能的，要避免阻塞操作，使用连接池、协程客户端等

2. **服务拆分粒度**：不要过度拆分，按业务领域划分，保持服务独立但不过于分散

3. **数据库优化**：善用MySQL 8.0的空间索引，地理位置查询性能提升显著

4. **监控告警**：建立完善的监控体系，及时发现和处理问题

### 产品层面

1. **文档先行**：好的API文档能让开发者快速上手，降低接入门槛

2. **示例代码**：提供Vue/React/小程序等多语言示例，覆盖主流技术栈

3. **渐进式开放**：先开放基础接口，逐步开放高级能力

4. **社区运营**：建立开发者社区，收集反馈，持续改进

### 商业层面

1. **灵活接入**：提供共享API和独立部署两种模式，满足不同阶段需求

2. **公益初心**：始终记得为什么出发，为公益项目降低技术门槛

3. **可持续发展**：合理的商业化能让平台更好地服务公益

4. **开放共赢**：欢迎更多项目接入，共同创造价值

## 展望

未来计划：

1. **扩展服务**：验证服务已支持邮箱验证（发送验证码、邮箱验证）和阿里云短信验证（代码已完成并测试通过），后续更换通过审核的短信模板ID即可正常使用

2. **多区域部署**：在更多地区部署节点，降低延迟

3. **AI能力开放**：将AI算命等服务标准化后对外开放

4. **社区建设**：建立开发者社区，鼓励共享代码和经验

5. **接入示例**：提供更多接入示例（Vue、React、微信小程序等）

6. **管理后台**：开发可视化的域授权管理系统

## 接入指南

### 快速接入

1. **联系授权**：通过微信、邮箱或电话申请域名授权

2. **获取密钥**：获取项目的API密钥和配置信息

3. **配置调用**：根据文档配置API调用

4. **测试上线**：本地测试通过后即可上线

**本地开发说明**：

- localhost、127.0.0.1等本地域名默认已授权

- 开发过程中无需额外配置

### 技术支持

- **微信**：kmwmkj

- **邮箱**：admin@lck.yn.cn

- **电话**：15687658489（微信同号）

- **API文档**：https://api.micro.lck.yn.cn/

## 结语

技术不仅是工具，更是一种改变世界的力量。作为一名开发者，我有幸能用自己的专长帮助他人，这让我感到无比充实。

我希望通过这个共享API平台，降低技术门槛，让更多人能够快速实现自己的想法。无论你是想做公益项目，还是想开发商业应用，都可以在这里找到你需要的基础能力。

如果你也想接入我的共享API平台，欢迎联系我。让我们一起用技术创造价值，让世界变得更美好一点。

**联系方式**：

- 微信：kmwmkj

- 邮箱：admin@lck.yn.cn

- 电话：15687658489（微信同号）

- 网关地址：https://api.micro.lck.yn.cn/

---

**作者简介**：李成坤（Ckli），后端工程师，系统架构师，技术总监。从事PHP开发近20年，现任云南某科技公司技术总监。热衷于公益事业，用技术帮助需要帮助的人。

个人主页：https://www.lck.yn.cn/

技术博客：https://blog.lck.yn.cn/

宝塔的情况下 certbot 证书安装管理(亲测)

Mon, 22 Dec 2025 21:47:18 +0800

1，安装

yum install certbot python3-certbot-nginx -y

2,检查一下nginx的配置文件

nginx -t

3,宝塔安装的，nginx目录没有在etc下，会有错误提示，需要更改下命令，加上nginx的目录配置

certbot --nginx --nginx-server-root=/www/server/nginx/conf/

4，运行成功后，

第一个填写使用的邮箱

第二个选择Y

第三个选择你要配置的域名的序号

5，重启nginx

6，证书只有3个月的有效期，需要设置一个定时任务，之后增加上

7，

设置自动续签，为了避免手动续签的麻烦，可以将续签操作添加到crontab计划任务中（执行命令 crontab -e ，把以下定时任务内容写入），确保证书在到期前自动更新：

0 0 1 * * certbot renew --quiet --renew-hook 'sudo systemctl reload nginx' > /dev/null 2>&1

特别说明：来源于网络，但本人已亲测整理通过。

七家坡的 “摆渡人”：在代码与乡野间，搭一座公益的桥

Sun, 28 Sep 2025 10:38:30 +0800

敲下最后一行代码，我望着电脑屏幕上 “七家坡基层互助站” 的顺风车页面，上面 “燃灯寺→七家坡” 的行程信息清晰可见。窗外没有高楼大厦的霓虹，只有乡野夜晚的静谧，可我知道，这行代码背后，是无数个等待着 “被摆渡” 的乡亲。

做公益这件事，我走了好多年。中间有过委屈，有过难，甚至看着自己搭建的平台，明明能帮人，却因 “不会吆喝” 而少有人问津时，也会陷入迷茫。但每当想起乡镇里，有人为了赶一趟班车，天不亮就守在路边；残障朋友想找份能做的活，却被大平台的门槛挡在门外；还有那些假期里，为买不到票、怕堵车而焦虑的身影，我就觉得，手里的键盘还得继续敲。

现在的 “七家坡基层互助站”，技术上，我用 Swoft2.0 搭建独立网关和服务，让数据库与服务分离部署，为的是高可用、高并发，能承载更多乡亲的使用需求。前端从微信小程序转向 Vue3 做 PC+H5 自适应，绕开企业认证的各种限制，就想让更多人，哪怕是乡镇村级的乡亲，都能无阻碍地用上。

平台里的顺风车 / 拼车服务，是我扎根基层的第一个尝试。大假里，有人本就要从 A 点到 B 点，愿意捎上同路的人；也有人买不到票，或是不想开车添堵，或是想省点钱。这个平台，就是要把这些需求连起来。后续，我还会上线运营班次查询，让乡亲们不用再在路边盲目等车；做残障招聘，帮残障朋友找到能实现价值的工作；还有家政等服务，一步步来，做完一个就上线一个。

有人说，腾讯、阿里、美团这些大平台已经做得够好。可我清楚，他们的出发点和模式不同，带着资本的属性，很多服务到了省市级就难再下沉。而我要做的，就是补这个缺口，做乡亲们用得上、用得顺的公益平台。

这些年，我一头扎进深层技术，对美感没什么研究，拍不出多精致的照片。但我站在乡镇街头，指着电脑上的平台页面时，心里是踏实的。因为我知道，这不是什么花哨的东西，是能真真正正帮到人的工具。

我信儒释道，却不受限于任何一教，只秉持着 “持身正，不损人” 的念头。技术是术，本身无好坏，用它来为乡亲们搭一座公益的桥，就是我认定的 “正”。

未来的路还长，代码要继续写，服务要继续加。我只想做七家坡，做更多基层地方的 “摆渡人”，在代码的世界与乡野的土地间，稳稳地搭起一座公益的桥。

熊猫库存，不只是库存----企业数字化移动办工系统（数字企业SaaS系统）

Fri, 31 Mar 2023 09:52:26 +0800

一、系统介绍

1-01、应用名称

熊猫库存，不只是库存----企业数字化移动办工系统（数字企业SaaS系统）

1-02、部署

系统可公有化部署，也可私有化部署（应对某些产品OR数据为高隐私，不便让让外部人员看到的产品）

1-03、适用场景及基本功能

A：）适用于一切实体生产或原材料企业数字化转型。销售、借还、结算，等数据随着线上操作自动生成。省去人工记录、统计等不可避免的错误等。使企业全身心投入到自己的生厂OR加工中去。

若产品为贵重、稀缺类，本系统还支持服务商（担保服务）

B：）适用于直播带货的企业OR个人对所需货品的借、还、售

1-04、特色

A：）支持多仓库。（一个商户可以有多个仓库）

B：）支持员工及权限管理。（老板帐号不受权限控制，员工帐号可以分别给货品操作、帐单权限）

C：）支持只做熟人生意。（关闭公开展示后，其他人员在供货中心看不到本货品。仅货主方能从仓库中选择并创建订单）

D：）支持物品曝光。（开启公开展示后，供货中心可见且可下单。可推入地滩区展示。货品可在PC端引流展示）

E：）支持多价格。（成本价、借货价、一口价），借货价：可默认也可因人而异。

F：）支持服务商。（为借还货双方提供送货及结算服务，使借还双方不用接触，以确保货品、资源、财产等安全）

G：）支持电子帐单。（自动生成电子帐单，并可以打印纸质帐单。线上、线下双保险）

H：）支持货主自定义货号、可生成系统唯一条码。（条码与商户绑定，当条码所绑定的货品售出后，可另绑定货品）

I：）支持再次转借、售。（确认收货后，会在借货方仓库自动生成货品基本数据，商户可设置价格后再次转借、售）

J：）支持一键导图。（保存本地，用户自行到其他所有平台售卖）

二、系统使用（微信小程序）

2-01，注册

系统支持用户名+密码、手机号+密码、邮箱号+密码三种常规注册方式+微信登录自动注册方式。且册并登录成功后，可添加、解绑其他登录方式。微信登录自动生成的用户未发生业务时，可以自行注销。

2-02，实名认证

只要是后期需要操作的帐号，都需要进行实名认证（国家公安库核实）

2-03，企业入驻

2-04，创建仓库

2-05，邀情微信好友为员工（可操作业务）

2-06，员工权限管理

2-07，产品管理（添加，编辑，特殊属性管理等）

2-08，生成订单（两种方式 a：取货方在供货中心选对货品下单 b：供货方在仓库中选择货品下单）

2-09，订单操作，若为供货方创建则取供双方员工扫码完成货品交接，否则双方匀不直接操作，而是与服务商操作

2-10，还货（结算）。注：目标商户只能是来源商户。未还货或结算完成的货物可再次操作。

2-11，订单查看（boss 或有订单权限的员工可以看所有员工的订单，其他员工仅能看到自己产生的订单）

TP6 swagger(自动生成 api 接口文档，根据需要开启或关闭)

Sun, 13 Jun 2021 01:39:23 +0800

[以下内容来自本人一边做一边记录。本打算直接录视频，但发现有些问题更需要先解决。固先发文字教程]

[虽然还不太会录，但是今天还是录成了视频]

一，安装配置 TP6，及多应用。

【这里就不说了,自行查看】

官方手册 https://www.kancloud.cn/manual/thinkphp6_0

二，打开 php 项目安装 swagger-php 扩展

composer require zircote/swagger-php

三，为 swagger 添加路由

注意：分别在多应用的路由中写路由，而不是到全局路由中写

比如：项目下有三个应用 index(pc站应用) api(前台接口应用) admin（后台接口应用）

因为，api和admin应用需要生成文档，所以在其下的路由中书写，不需要的应用就不用管它。

我的例子中路径分别为：

app\api\route\route.php 中内容如下：

<?php

use think\facade\Route;

Route::get('/swagger', function() {

$openapi = \OpenApi\scan('../app/api/controller');//各应用下的controller

header('Content-Type: application/json');

echo $openapi->toJson();

});

app\admin\route\route.php （照着上面写，记得把路径中的api改成admin）

四，下载 swagger 的用户界面 swagger-ui

下载，clone 都行。你自怎么用方便就怎么用

git clone https://github.com/swagger-api/swagger-ui.git

解压后项目根目录下的 public 下 swagger-ui 目录

修改 public/swagger-ui/dist/index.html 文件中的数据来源

如下：

// url: "https://petstore.swagger.io/v2/swagger.json", // 这里是官方给的实例接口数据

url: "/swagger/docs/swagger.json", //这里是我们自己项目中自动生成的接口数据

还有语言 en 改为 zh-cn 。也可以不管它

五，建控制器 Swagger.php (注意：很多教程都掉了这一步，以讹传讹。这也是我会去亲测后，发完整教程的原因。)

在需要生成文档的应用下的 controller 目录下建控制器

这里的控制器名称来源于第三步中写的路由地址 swagger

Swagger.php 中只需要有类 Swagger 就可以了，不用写方法。

同时写入文档配置信息（共用的部份），以后要改也方便，只需要改这个文件里的配置

如下：

<?php

namespace app\api\controller;

use think\Request;

use app\api\Base;

/**

* @OA\Swagger(

* schemes={"http","https"},

* host="api.cnfeicui.com",

* basePath="/",

* @OA\Info(

* version="1.0.0",

* title="中国翡翠API-【前台：支持在线测试】",

* description="注：请在接口路径前加上应用地址!如下<br>1、线上<br>前台API添加：http://api.cnfeicui.com/<br>后台api添加：http://api.admin.cnfeicui.com/<br>2、线下<br>前台API添加：http://api.dev.cnfeicui.com/<br>后台api添加：http://api.admin.dev.cnfeicui.com/",

* termsOfService="",

* @OA\Contact(

* email="admin@lck.yn.cn"

* ),

* @OA\License(

* name="cnfeicui",

* url="https://api.cnfeicui.com"

* )

* ),

* @OA\ExternalDocumentation(

* description="http://www.lck.yn.cn",

* url="http://www.lck.yn.cn"

* )

* @OA\SecurityScheme(

* type="http",

* in="header",

* name="Authorization",

* scheme="bearer",

* securityScheme="bearerAuth",

* bearerFormat="JWT"

* )

class Swagger extends Base

{

}

六，在需要生成文档的接口方法前，以 swagger 的要求写注释，即可自动生成接口文档

如需对登录（ Login.php ）接口生成文档。

<?php

namespace app\api\controller;

use app\api\Base;

use think\Request;

class Login extends Base

{

/**

* @OA\Post(path="/login/system",

* tags={"用户登录"},

* summary="系统帐号登录",

* @OA\Parameter(name="deviceid", in="header",description="设备唯一值",required=true,@OA\Schema(type="string")),

* @OA\RequestBody(

* @OA\MediaType(

* mediaType="content-type/json",

* @OA\Schema(

* @OA\Property(description="帐号", property="identifier", type="string"),

* @OA\Property(description="密码", property="credential", type="string"),

* required={"identifier","credential"})

* )

* ),

* @OA\Response(

* response="100",

* description="返回结果请以真实API拿数到数据为准",

* )

public function system(Request $request)

{

return json(['code'=>0,'msg'=>'这里是返回提示','data'=>[]]);

}

自此，swagger 就算配成功。

七，由于安全等多方面原因，我们生产环境是需要关闭 swagger 的

回到第三步，我们添加的路由文件中

先引入 Env

use think\facade\Env;

再修改路由方法：在其中加入环境变量判断。

在需要开启文档的环境 .env 文件中配置 SWAGGER.START 的值为：true 。未配置或 false 提示关闭

修改后的路由文件( route.php )如下：

<?php

use think\facade\Route;

use think\facade\Env;

Route::get('/swagger', function() {

if(Env::get('SWAGGER.START',0)){

$openapi = \OpenApi\scan('../app/api/controller');

header('Content-Type: application/json');

echo $openapi->toJson();

}else{

echo'{

"openapi": "3.0.0",

"info": {

"title": "中国翡翠API-【前台：支持在线测试】",

"description": "当前环境，已关闭！",

"termsOfService": "",

"contact": {

"email": "admin@lck.yn.cn"

"license": {

"name": "Private License",

"url": "URL to the license"

"version": "1.0.0"

"paths": {},

"components": {

"securitySchemes": {

"bearerAuth": {

"type": "http",

"name": "Authorization",

"in": "header",

"bearerFormat": "JWT",

"scheme": "bearer"

}

"externalDocs": {

"description": "http://www.lck.yn.cn",

"url": "http://www.lck.yn.cn"

}

}';

}

});

10秒一个API接口文档，你也可以。

Wed, 21 Aug 2019 22:58:30 +0800

一，phprap 的各方面优点，我就不说了。需要看的朋友上其官方网站 http://www.phprap.com

二，eidt by Ckli

1，修改数据库字段类型，长度

2，修改model，使添加API接口时自动生成需重复性填写内容，解除后端人员写API文档的烦恼。

3，修改view中默认网关地址。

4，数据库在根目录下 lck-data 下，登录邮箱地址：258205740@qq.com 默认密码：123456

5，Ckli 官方网站： http://www.lck.yn.cn Ckli blog：http://blog.lck.yn.cn 欢迎交流

6，下载地址：https://gitee.com/lck8203/phprap

三，线上测试观看

TP3.2.3(thinkphp3.2.3) 关联模型之---非主键关联（已亲测可用）

Mon, 29 Apr 2019 14:50:18 +0800

TP3.2.3(thinkphp3.2.3) 关联模型之---非主键关联（已亲测可用）、TP5，暂无时间测试，如果人兄有测试结果，烦请发邮件给我一下，我好做一下更改。以方便遇到同样问题的朋友、

我的应用场景是：有一个表（风格：style表---字段：1，id 2，title）,另一个表（安例：anli：字段：style 存储风格表中的 title 的内容，这里非 id，也非主键）

<?php

namespace Wap\Model;

use Think\Model\RelationModel;

class StyleModel extends RelationModel{

protected $_link = array(

//风格对应anli

'anlis'=>array(

'mapping_type' => self::HAS_ONE,

'class_name' => 'Anli',

'mapping_key' =>'title',// style 表字段。

'foreign_key' =>'style', // anli（表），即关联模型对应表中的字段名。

'mapping_order' => 'id ASC',

'mapping_fields' => 'id,pic_m_l',

);

}

希望对你有帮助。

申明：本文所道之处，由本人（Lck，Ckli）亲测可用。

laravel-admin 集成 ueditor

Thu, 29 Nov 2018 20:49:55 +0800

因为我最近集成 ueditor 看到了网上很多文章，要么这里错了，要么哪里错了。现在我把过程发给大家，按照我的步骤走下就能OK了哈。

1，下载ueditor 解压放入你的项目 /public/packages/

2，app/Admin/Extensions/ 下新建文件名：UEditor.php 文件内容如下：

<?php

namespace App\Admin\Extensions;

use Encore\Admin\Form\Field;

class UEditor extends Field

{

protected $view = 'admin.ueditor';

protected static $css = [];

protected static $js = [

'/packages/utf8-php/ueditor.config.js',

'/packages/utf8-php/ueditor.all.js'

];

public function render()

{

$name = $this->formatName($this->column);

$this->script = <<<EOT

//解决第二次进入加载不出来的问题

UE.delEditor("container");

var ue = UE.getEditor('container',{

elementPathEnabled: false,

enableContextMenu: false,

autoClearEmptyNode: true,

wordCount: false,

imagePopup: false,

autotypeset: {indent: true, imageBlockLine: 'center'}

});

ue.ready(function() {

ue.execCommand('serverparam', '_token', '{{ csrf_token() }}');

});

EOT;

return parent::render();

}

3， resources/views/admin/ 下新建文件：ueditor.blade.php 内容如下：

<div class="form-group {!! !$errors->has($errorKey) ?: 'has-error' !!}">

<label for="{{$id}}" class="col-sm-2 control-label">{{$label}}</label>

@include('admin::form.error')

{!! old($column, $value) !!}

</textarea>

@include('admin::form.help-block')

</div>

4，app/Admin/bootstrap.php 修改此文件内容如下（如果没有，请自已新建）：

<?php

use App\Admin\Extensions\UEditor;

use Encore\Admin\Form;

Form::extend('ueditor', UEditor::class);

5，在你自己控制器中的 form 方法里调用如：

$form->ueditor('experience','职业经历');

6，上图看效果

最后，因为ueditor 官方提供下载地址是国外的，如果你下载不了，可以去我的 blog 找我提供的百度网盘下载地址和提取码。

Lck 的 blog https://blog.lck.yn.cn/?id=3

百度编辑器(ueditor)下载不了的同学看过来！

Thu, 29 Nov 2018 19:49:17 +0800

最近因为想把百度编辑器添加到 laravel-admin 去官网下载。一直都下不出来。经查看，官网放出的连接是国外的。后来想起自已电脑安装了蓝色 chrome （已跳墙）。马上打开，几十秒就下下来了。现为了方便国内未跳墙小伙伴们下载。本人已将下载的 ueditor1_4_3_3-utf8-php.zip

上传至百度云盘（未做过任何更改）。以方便大家。以下是下载链接和提取码：

链接: https://pan.baidu.com/s/1y3U_fblHWoQPOSoIhbU8gQ 提取码: p6wp