API와
요청·응답 이해하기理解 API
与请求·响应
처리 결과가 응답으로 돌아오는 과정을 읽습니다.理解用户行动如何变成请求,
结果如何以响应返回。
버튼을 누른 뒤, 무슨 일이 일어날까?按下按钮后发生了什么?
사용자가 “과학 보고서 쓰기”를 입력하고 추가를 누릅니다. 화면은 기능에 요청을 보내고, 기능은 결과를 응답합니다.用户输入“写科学报告”并按下添加。画面向功能发送请求,功能把结果作为响应返回。
사용자의 행동은 어떤 요청이 되고,
서비스는 어떤 응답을 돌려줘야 할까?用户行动会变成什么请求?
服务应该返回什么响应?
9회는 사용자 전체 흐름을 설계했습니다. 10회는 핵심 행동 하나에서 요청과 응답이 오가는 방식을 볼 것입니다.第 9 次课设计了整体用户流程。第 10 次课聚焦一个核心行动中请求与响应的往返。
API는 약속된 창구다API 是约定好的窗口 핵심核心
| 예例子 | 의미意思 |
|---|---|
/api/tasks | 할 일을 다루는 약속된 주소处理待办的约定地址 |
| 추가添加 | 새 할 일을 처리해 달라는 의도处理新待办的意图 |
task | 보낼 할 일 내용要发送的待办内容 |
사용자 흐름을 요청·응답으로 읽는다用请求·响应阅读用户流程 핵심核心
9회의 흐름은 그대로 유지합니다. 오늘은 그 중간에 오가는 데이터를 더 세밀하게 봅니다.第 9 次课的流程保持不变,今天只更仔细地看中间往返的数据。
내 흐름 한 단계를 넷으로 쪼갠다把我的流程中的一步拆成四步 실습实践
9회에 적은 사용자 흐름에서 핵심 기능이 일어나는 단계 하나를 고릅니다. 그 한 단계를 위의 네 칸으로 쪼개 봅니다.从 9 次写的用户流程里,挑出核心功能发生的那一步。把那一步拆成上面的四格。
| 칸格 | 내 서비스에서는在我的服务里 |
|---|---|
| ① 사용자 행동① 用户动作 | |
| ② 화면이 보내는 것② 画面发送什么 | |
| ③ 서비스가 하는 일③ 服务做什么 | |
| ④ 화면에 나타나는 것④ 画面上出现什么 |
흐름을 다시 설계하지 않습니다. 9회에 적은 그 흐름의 한 단계를 그대로 가져와 안을 들여다보는 것뿐입니다.不是重新设计流程。只是把 9 次写好的那条流程中的一步拿过来,看看里面。
GET과 POST는 요청의 의도를 나타낸다GET 与 POST 表示请求意图 핵심核心
| 방법方法 | 쉽게 말하면简单来说 | 예例子 |
|---|---|---|
GET | 이미 있는 정보를 보여 달라把已有信息给我 | 기록 목록 불러오기读取记录列表 |
POST | 데이터를 보낼 테니 처리해 달라我发数据,请处理 | 새 기록 추가, 입력값 계산添加记录、计算输入值 |
“나의 독서 기록을 보여 줘”는 GET, “오늘 읽은 책을 기록해 줘”는 POST에 가깝습니다.“给我看阅读记录”更接近 GET,“记录今天读的书”更接近 POST。
기능이 정보를 받는 일인지, 데이터를 보내 처리하는 일인지만 판단하면 됩니다.只要判断功能是获取信息,还是发送数据并处理。
이 행동은 GET인가 POST인가这个动作是 GET 还是 POST 실습实践
이름을 외우는 것이 아닙니다. 이미 있는 것을 보여 달라는 일인지, 무언가를 보내 처리해 달라는 일인지만 판단합니다.不是背名字。只判断是「把已有的东西显示出来」还是「送点东西过去处理」。
| # | 사용자가 하는 일用户做的事 | GET · POST | 왜 그렇게 봤나为什么这么看 |
|---|---|---|---|
| 1 | 기록 목록을 불러온다载入记录列表 | ||
| 2 | 새 기록을 추가한다添加新记录 | ||
| 3 | 입력한 값으로 계산한다用输入的值做计算 | ||
| 4 | ← 내 서비스의 핵심 행동← 我的服务的核心动作 |
- 세 번째 줄에서 계산도 POST라는 것을 확인했다. 보내서 처리하는 일이기 때문이다.第三行确认了计算也是 POST,因为是送过去处理。
- 네 번째 줄은 내 서비스로 적었다.第四行是用自己的服务写的。
JSON은 ‘이름: 값’으로 데이터를 담는다JSON 用“名称:值”装载数据 핵심核心
JSON은 요청과 응답에서 데이터를 표현하는 방식입니다. Python의 사전과 비슷한 모양입니다.JSON 是请求与响应中表示数据的方式,外形与 Python 字典相似。
{ "task": "과학 보고서 쓰기" }{
"ok": true,
"message": "할 일을 추가했습니다."
}| 이름名称 | 값值 | 의미意思 |
|---|---|---|
task | 과학 보고서 쓰기写科学报告 | 보낸 할 일发送的待办 |
ok | true | 처리 성공处理成功 |
message | 추가했습니다已添加 | 화면의 안내画面提示 |
괄호와 쉼표를 외우지 않습니다. AI가 제안한 내용에서 이름과 값의 의미를 읽습니다.不背括号和逗号,只读懂 AI 提议中名称与值的意思。
내 요청과 응답을 이름:값으로把我的请求和响应写成「名称:值」 실습实践
괄호와 쉼표는 신경 쓰지 않습니다. 어떤 이름에 어떤 값이 들어가는지만 적습니다. 3-2에서 만든 이름표 묶음과 같은 모양입니다.不用管括号和逗号。只写哪个名称里放哪个值。和 3-2 做的名牌集合是一样的样子。
| 보내는 것 · 이름发送 · 名称 | 값의 예值的例子 |
|---|---|
| 받는 것 · 이름接收 · 名称 | 값의 예值的例子 |
|---|---|
| ok | true 또는 falsetrue 或 false |
| message | 화면에 보여 줄 안내 한 줄要显示在画面上的一句提示 |
ok 와 message 는 거의 모든 서비스가 씁니다. 그대로 두고 내 서비스에만 필요한 이름을 아래 빈 줄에 적습니다.ok 和 message 几乎每个服务都用。保留它们,把自己服务特有的名称写在下面的空行里。
성공도 실패도 다음 행동을 알려줘야 한다成功与失败都要告诉下一步 핵심核心
| 결과结果 | 응답의 내용响应内容 | 화면의 역할画面作用 |
|---|---|---|
| 성공成功 | 성공 여부와 결과是否成功与结果 | 원한 결과 표시显示期望结果 |
| 입력 문제输入问题 | 무엇을 고쳐야 하는지要修改什么 | 수정과 다시 시도 방법修改与重试方法 |
| 서비스 문제服务问题 | 처리하지 못했음未能处理 | 사용자 탓으로 돌리지 않고 다시 시도 안내不归咎用户,提示重试 |
“오류”보다 “할 일을 한 글자 이상 입력한 뒤 다시 추가해 보세요”가 더 유용합니다.比起“错误”,“请输入至少一个字后重试”更有用。
사용자가 결과를 이해하고 다음 행동을 선택할 수 있는지만 확인합니다.只确认用户能否理解结果并选择下一步。
이 안내를 받으면 다음에 뭘 할까收到这句提示,接下来该做什么 실습实践
왼쪽 안내를 받은 사용자가 다음에 무엇을 할 수 있는지 판단합니다. 모르겠으면 다음 행동이 보이도록 고쳐 씁니다.判断收到左边提示的用户接下来能做什么。如果不知道,就改写成能看出下一步的样子。
| # | 서비스가 보낸 안내服务发出的提示 | 다음 행동을 알 수 있나能知道下一步吗 | 고쳐 쓴 안내改写后的提示 |
|---|---|---|---|
| 1 | 오류错误 | ||
| 2 | 입력값이 올바르지 않습니다输入值不正确 | ||
| 3 | ← 내 서비스가 보낼 실패 안내← 我的服务要发的失败提示 |
- 고쳐 쓴 안내에 사용자가 할 행동이 들어 있다. 「다시 …해 보세요」 같은 말이다.改写后的提示里有用户要做的动作,比如「请再…试一次」。
- 서비스 쪽 문제일 때는 사용자 탓으로 돌리지 않았다.如果是服务端的问题,没有把责任推给用户。
하나의 Next.js 프로젝트 안에서 연결한다在一个 Next.js 项目内连接 핵심核心
- 프론트엔드와 백엔드를 별도 프로젝트로 나누지 않습니다.不把前端与后端拆成两个项目。
- 포트·CORS·인증 헤더·Postman은 제외합니다.不学端口、CORS、认证请求头、Postman。
- 외부 API와 학생 개인 API 키를 쓰지 않습니다.不使用外部 API 和学生个人 API 密钥。
오늘은 자신의 서비스 안에서 화면과 기능을 연결하는 내부 API를 만듭니다.今天要做的是在自己服务内连接画面与功能的内部 API。
내 서비스의 핵심 API를 말로 정리한다用语言整理我的核心 API 실습实践
주소와 방법은 AI 제안 후에 적어도 됩니다. 먼저 사용자 행동, 보낼 데이터와 받을 데이터를 자신의 말로 적습니다.地址与方法可在 AI 提议后填写。先用自己的话写用户行动、发送与接收的数据。
- 사용자의 핵심 행동用户核心行动
- 요청 주소와 방법 — AI 제안을 받은 뒤에 적는다请求地址与方法 —— 收到 AI 提议后再写
- 보낼 데이터要发送的数据
- 성공하면 받을 데이터成功时接收的数据
- 실패하면 받을 안내失败时接收的提示
- 응답 뒤 화면에 보여 줄 것响应后画面显示内容
학생은 자신의 흐름에 필요한 요청과 응답의 의미를 설명하면 됩니다.学生只需要说明自己流程中请求与响应的意义。
API가 작동해도 아직 기억하지는 못한다API 能运行,但还不能记住 핵심核心
11회에는 새 프로젝트를 만드는 것이 아니라, 오늘의 요청·응답에 SQLite 저장과 조회를 덧붙입니다.第 11 次课不是重做项目,而是在今天的请求·响应中加上 SQLite 保存与查询。
핵심 기능을 실행한 뒤 페이지를 새로 열거나 프로젝트를 다시 시작해 보세요. 무엇이 사라지는지가 11회의 출발점입니다.执行核心功能后重新打开页面或重启项目。消失的内容就是第 11 次课的起点。
확인 문제检查题
해설 보기查看解析
보내는 쪽과 받는 쪽이 무엇을 어디로 보내고 무엇을 돌려받을지 미리 정해 두었기 때문입니다. 약속이 없으면 화면은 무엇을 보낼지 모르고, 기능은 무엇을 돌려줄지 모릅니다.因为发送方与接收方事先约好了往哪里发什么、又会收到什么。没有约定,画面不知道该发什么,功能也不知道该回什么。
창구라는 말은 정해진 자리라는 뜻입니다. 아무 데나 말을 걸 수 없고 정해진 주소로만 요청합니다.“窗口”指的是固定的位置。不能随便找地方说话,只能往约定的地址发请求。
GET과 POST를 어떻게 구분할 수 있는가?怎样区分 GET 与 POST?해설 보기查看解析
요청의 의도로 구분합니다. 이미 있는 정보를 보여 달라면 GET, 데이터를 보낼 테니 처리해 달라면 POST입니다.按请求的意图来分。要看已有的信息用 GET,发数据过去让它处理用 POST。
“내 기록을 보여 줘”는 GET, “오늘 읽은 책을 기록해 줘”는 POST입니다. 이름을 외우는 것이 아니라 둘 중 어느 쪽인지 판단하면 됩니다.“给我看我的记录”是 GET,“把今天读的书记下来”是 POST。不是背名字,而是判断属于哪一种。
해설 보기查看解析
오가는 데이터를 이름과 값의 쌍으로 담는 그릇입니다. task라는 이름 옆에 값이 있으면, 받는 쪽은 그것이 할 일의 내용임을 알 수 있습니다.它是把往返数据装成名称与值成对的容器。看到 task 这个名字旁边的值,接收方就知道那是待办的内容。
괄호와 쉼표를 외울 필요는 없습니다. AI가 만든 요청·응답에서 어떤 이름에 어떤 값이 들어 있는지 읽으면 됩니다.不必背括号和逗号。只要能在 AI 写出的请求与响应里读出哪个名字装着哪个值就行。
확인 문제检查题(이어서)(续)
해설 보기查看解析
실패했다는 사실만 알려 주면 사용자가 거기서 멈추기 때문입니다. 무엇이 잘못됐고 어떻게 고치는지 알아야 정상 흐름으로 돌아갈 수 있습니다.只告诉他失败了,用户就停在那里了。要知道哪里错了、怎么改,才回得到正常流程。
“오류”보다 “할 일을 한 글자 이상 입력한 뒤 다시 추가해 보세요”가 좋은 응답입니다. 서비스 쪽 문제라면 사용자 탓으로 돌리지 않고 다시 시도할 수 있다고 알려 줍니다.比起“错误”,“请输入至少一个字后再添加”才是好响应。若是服务本身的问题,就不要归咎用户,告诉他可以再试一次。
해설 보기查看解析
11회에 새 프로젝트를 만드는 것이 아니라, 오늘 만든 요청·응답에 SQLite 저장과 조회를 덧붙입니다. 화면 ↔ API가 화면 ↔ API ↔ SQLite가 됩니다.第 11 次课不是另做一个项目,而是在今天做好的请求·响应上加进 SQLite 的保存与查询。画面 ↔ API 变成画面 ↔ API ↔ SQLite。
그래서 오늘 다시 열었을 때 무엇이 사라지는지 확인해 두는 것이 11회의 출발점이 됩니다.所以今天确认重新打开后什么不见了,就成了第 11 次课的起点。
“내 서비스에서 사용자가 ______을 하면 화면은 ______을 보내고, 돌아온 ______을 화면에 보여 준다.” 세 빈칸을 채워 보세요.“在我的服务里,用户做了 ______,画面就发送 ______,再把收到的 ______ 显示出来。”请填这三个空。
핵심 정리와 완료 확인核心小结与完成确认
- 사용자 행동이 요청과 응답으로 이어지는 과정을 설명할 수 있다.能说明用户行动如何连到请求与响应。
- GET과 POST의 기본 차이를 알고 있다.知道 GET 与 POST 的基本差别。
- JSON의 ‘이름: 값’을 읽을 수 있다.能读懂 JSON 的“名称:值”。
- 나의 API 약속표에 핵심 내용을 적었다.已在自己的 API 约定表中写下核心内容。
- API는 화면과 기능 사이의 약속된 창구다.API 是画面与功能之间约定好的窗口。
- 학생은 보낼 데이터와 받을 데이터를 설명하면 된다.学生能说明要发送与接收的数据即可。
- 11회에 오늘의 API에 SQLite를 연결한다.第 11 次课会在今天的 API 上连接 SQLite。
AI가 코드를 수정하기 전에 요청·응답·화면 변화를 먼저 설명하게 하고, 약속표와 맞을 때만 핵심 API 하나를 연결합니다.让 AI 在改代码前先说明请求、响应与画面变化,只有与约定表一致时才连接一个核心 API。
10-2. AI와 핵심 API 연결하기 →